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

# How to Handle API Errors in the Honestly Export API

> Learn how the Honestly Export API signals failures with HTTP status codes and a structured JSON error object you can parse in your integration.

The Honestly Export API uses standard HTTP status codes and returns a consistent JSON error object so your integration can handle failures gracefully.

## Error response format

When a request fails, the API returns a JSON body with a top-level `error` object:

```json theme={null}
{
  "error": {
    "code": 5003,
    "message": "Validation failed",
    "errors": [
      {
        "field": "email",
        "message": "Email is required"
      }
    ]
  }
}
```

Each field in the error object serves a distinct purpose:

* **`message`** — Always present. A human-readable description of what went wrong.
* **`code`** — Optional. A numeric error code useful when contacting support.
* **`errors`** — Optional. An array of field-level validation errors. Each entry contains a `field` name and a `message` explaining the problem with that field.

## HTTP status codes

| Status Code                 | Meaning                    | When it occurs                                                                                                                        |
| --------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | Invalid request parameters | The request was malformed — for example, `limit` exceeds the maximum, a required field is missing, or a date-time value is malformed. |
| `401 Unauthorized`          | Missing or invalid API key | The `X-Api-Key` header was not provided or the key supplied is not recognised.                                                        |
| `500 Internal Server Error` | Unexpected server error    | Something went wrong on Honestly's side. Retry the request with exponential backoff.                                                  |

## Handling errors in practice

Follow these best practices to make your integration resilient to API errors:

* Always check the HTTP status code before parsing the response body.
* Log the full error object for debugging — the `message` and `code` fields are especially useful.
* For `500` errors, retry the request with exponential backoff rather than failing immediately.
* For `401` errors, verify your API key is correctly passed in the `X-Api-Key` header.
* For `400` errors, inspect the `errors` array for field-level details pointing to the exact invalid input.

<Tip>
  The `message` field is always set. Use it in error logs and alerts. The `code` field, when present, is useful when contacting [service@honestly.com](mailto:service@honestly.com) for support.
</Tip>