How to Handle API Errors in the Honestly Export API

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:

{
  "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.

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 for support.

​Error response format

​HTTP status codes

​Handling errors in practice

Error response format

HTTP status codes

Handling errors in practice