Error Documentation

Overview

The Liquidity API uses standard HTTP response codes to indicate request outcomes:

2xx - Success

4xx - Client errors (invalid parameters, auth failures, etc.)

5xx - Server errors (rare)

Error Object Format

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing", 
    "message": "Missing required parameter: email",
    "param": "email",
    "request_id": "req_abc123",
    "doc_url": "https://liquidity.arf.one/errors#parameter_missing",
    "details": {}
  }
}

Attributes

Field	Description
`type`	General category of the error
`code`	Specific identifier for the error
`message`	Human-readable explanation
`param`	Parameter causing the error (if applicable)
`request_id`	Unique identifier for the request
`doc_url`	Link to relevant documentation
`details`	Additional context (optional)

HTTP Status Codes

Code	Name	Description
200	OK	Success
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Authentication required
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Request conflicts with current state
422	Unprocessable Entity	Valid request, semantic errors
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error
502	Bad Gateway	Upstream server error
503	Service Unavailable	Server temporarily unavailable
504	Gateway Timeout	Upstream timeout

Error Types

`api_error`

Cause: Internal server issue
Solution: Retry with exponential backoff

`authentication_error`

Cause: Invalid or missing API key
Solution: Authorization header and credentials

`authorization_error`

Cause: Insufficient permissions
Solution: Check API key scope or access rights

`invalid_request_error`

Cause: Missing or malformed parameters
Solution: Validate request structure and parameters

`rate_limit_error`

Cause: Too many requests
Solution: Implement retry strategy with backoff

`validation_error`

Cause: Input fails validation rules
Solution: details object and validate input formats

Common Error Codes

Authentication

invalid_key - Invalid API key

missing_key - No API key provided

expired_key - API key has expired

Request

parameter_missing - Required parameter not included

parameter_invalid - Invalid parameter value

malformed_request - JSON structure is invalid

resource_not_found - Resource doesn't exist

Rate Limiting

rate_limit_exceeded - Too many requests

quota_exceeded - API quota exceeded

Validation

invalid_email - Invalid email format

invalid_phone - Invalid phone format

invalid_date - Invalid date format

value_too_long - Value exceeds maximum length

value_too_short - Value below minimum length

Error Handling Best Practices

1. Handle Errors Gracefully

2. Implement Retry Logic

3. Log Errors

Always log errors with the request_id field to aid debugging and customer support.

Troubleshooting

Problem	Solution
401 Unauthorized	Check API key, authentication method, expiration
429 Rate Limit	Implement retry logic, reduce request frequency
422 Validation	Verify required fields, formats, business rules
500 Internal	Retry after delay, check status page, contact support

Getting Help

Review the error type and code

Validate authentication and request structure

Apply appropriate error handling and retries

If unresolved, contact support with the request_id

For more information: API Documentation | Support

Errors

Error Documentation#

Overview#

Error Object Format#

Attributes#

HTTP Status Codes#

Error Types#

api_error#

authentication_error#

authorization_error#

invalid_request_error#

rate_limit_error#

validation_error#

Common Error Codes#

Authentication#

Request#

Rate Limiting#

Validation#

Error Handling Best Practices#

1. Handle Errors Gracefully#

2. Implement Retry Logic#

3. Log Errors#

Troubleshooting#

Getting Help#