The Acclaim API uses standard HTTP status codes and structured JSON error responses to indicate problems with a request. This guide explains how to interpret and handle those errors gracefully in your integration.

Error Format

Every error response includes a top-level error object with details about what went wrong.

Example:

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: amount",
    "details": {
      "violations": [
        {
          "field": "amount"
        }
      ]
    },
    "request_id": "req_7lYt4o2x"
  }
}

Status Codes

Code	Meaning
400	Bad request or validation failure.
401	Missing or invalid API key.
403	The key is valid but lacks permission.
404	Resource not found.
429	Too many requests; retry after a delay.
5xx	Server error; safe to retry with backoff.

Error Codes

The error.code field is a stable, machine-readable string that helps automate error handling. Common values include:

invalid_request
authentication_failed
resource_not_found
rate_limited
internal_error
permission_denied

Retry Guidance

Scenario	Retry?	Recommendation
Network timeouts or 5xx responses	✅	Retry with exponential backoff.
429 Too Many Requests	✅	Wait and retry after the indicated delay.
400, 401, 403, 404	🚫	Fix input or credentials before retrying.

Log the request_id in error responses — it helps Acclaim Support trace issues quickly.

Rate Limits

Acclaim applies rate limits to ensure reliability for all clients. If you exceed the limit, the API will return a 429 Too Many Requests response with a short retry window. Use exponential backoff and respect the Retry-After header if provided.