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

# Errors and Troubleshooting

> Understand API error responses, status codes, and best practices for debugging and recovery.

<Icon icon="triangle-exclamation" size={26} color="#4B5563" />

## Error Responses

Our API uses standard HTTP status codes to indicate success or failure. All error responses return a structured JSON body that includes a `code`, `message`, and optionally, `details`.

***

### Common HTTP Status Codes

| Code | Meaning               | Description                                                                   |
| :--- | :-------------------- | :---------------------------------------------------------------------------- |
| 200  | OK                    | Request was successful.                                                       |
| 201  | Created               | Resource was successfully created.                                            |
| 400  | Bad Request           | The request is invalid (e.g., missing fields, invalid format).                |
| 401  | Unauthorized          | Invalid or missing API key.                                                   |
| 403  | Forbidden             | Authenticated, but not allowed to perform the operation.                      |
| 404  | Not Found             | Resource not found or endpoint incorrect.                                     |
| 409  | Conflict              | Duplicate resource creation or logic conflict (e.g., reused idempotency key). |
| 429  | Too Many Requests     | Rate limit exceeded.                                                          |
| 500  | Internal Server Error | An unexpected server-side error occurred.                                     |
| 503  | Service Unavailable   | Temporary downtime or overload. Try again later.                              |

***

### Sample Error Response

```json theme={null}
{
  "code": "BAD_REQUEST",
  "message": "Missing required field: product_category",
  "details": {
    "field": "product_category",
    "expected_type": "string"
  },
  "request_id": "c749af13-5c99-4e3e-b43a-5cc2d94a8db2"
}
```

***

## Debugging Tips

* Check the `code` and `message` fields for immediate clarity on the error.
* Use the `request_id` when contacting support to help trace the exact call.
* Ensure your `Content-Type` is set to `application/json` and all required fields are included.

***

## Handling Rate Limits

If you receive a `429 Too Many Requests`, inspect the following response headers:

| Header                  | Description                                    |
| :---------------------- | :--------------------------------------------- |
| `X-RateLimit-Limit`     | Max requests per minute allowed                |
| `X-RateLimit-Remaining` | Number of remaining requests in current window |
| `X-RateLimit-Reset`     | Time (Unix epoch) when the limit resets        |

You should **back off and retry** after the reset window.

***

## Retrying Safely

For **paid endpoints**, we recommend using [Idempotency Keys](/api-reference/idempotency-keys) to prevent duplicate billing during retries.

***

## Still Stuck?

If an error persists, contact us at [support@antei.com](mailto:support@antei.com) and include:

* The `request_id` from the response
* Your API key type (`live` or `sandbox`)
* A short description of what you were trying to do

We're here to help.