Errors & responses

The API uses standard HTTP status codes to indicate the outcome of a request. Successful requests return 2xx; client and server problems return 4xx and 5xx respectively.

Common status codes

Status	Meaning	What to do
200 OK	The request succeeded.	Read the response body.
201 Created	A resource was created.	Use the Location header to find the new resource.
204 No Content	The request succeeded with no response body.	No action needed.
400 Bad Request	The request was invalid (validation failed or malformed input).	Inspect the validation errors and correct the request.
401 Unauthorized	Authentication is missing or invalid.	Check your X-API-Key and Authorization headers — see Authentication.
403 Forbidden	Authenticated, but not permitted to perform the operation.	Ensure your credentials have the required permission.
404 Not Found	The requested resource does not exist.	Check the identifier in the URL.
429 Too Many Requests	You have exceeded the rate limit.	Honour the Retry-After header and back off — see Rate limiting.
500 Internal Server Error	Something went wrong on the server.	Retry later; if it persists, contact support.

Validation errors (400)

A 400 response always contains a list of field-level errors under errors[]. Depending on where validation failed, a top-level message summary may also be present, so clients should treat message as optional and always read errors[].

Business-rule validation includes the summary message:

{
  "message": "Validation failed.",
  "errors": [
    {
      "message": "First name is required.",
      "field": "firstName"
    }
  ]
}

Request/model-binding validation (e.g. a malformed or missing field caught before the request reaches the business logic) omits the top-level message:

{
  "errors": [
    {
      "message": "First name is required.",
      "field": "firstName"
    }
  ]
}

• message — an optional human-readable summary of the problem. Present for business-rule validation, absent for model-binding validation, so do not depend on it always being set.
• errors[] — zero or more validation items, each with the offending field and a descriptive message. Always present.

Rate limit errors (429)

Rate limit responses use the following shape and set a Retry-After header (in seconds):

{
  "error": {
    "code": "TooManyRequests",
    "message": "Rate limit exceeded. Please retry after the specified period.",
    "retryAfterSeconds": 60
  }
}

Server errors (500)

For server errors, avoid retrying immediately in a tight loop. The API does not return internal detail in the response for security reasons; use the HTTP status code to drive your error handling.