> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withacclaim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Learn how to handle errors returned by the Acclaim API. This document covers HTTP status codes, common error types, and best practices for debugging and retries.

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:

```json theme={null}
{
  "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.