Errors - Chataigne Docs

Chataigne uses conventional HTTP status codes to signal the outcome of a request, and returns a consistent, machine-readable JSON envelope on every error. Read the HTTP status to decide how to react (retry, fix input, escalate), and read the error.type and error.code fields to decide what went wrong.

Errors are identical in shape across both API surfaces — the public Chataigne API (/v1) and the Admin API (/admin/v1). The base URL for all requests is https://server.chataigne.ai.

The error envelope

Every error response — regardless of status code or surface — has the same top-level shape: a single error object.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "currency must be one of CHF, EUR, GBP, BRL, USD, MXN.",
    "param": "currency",
    "request_id": "req_8sQx2pL0aZ",
    "details": {
      "allowed_values": ["CHF", "EUR", "GBP", "BRL", "USD", "MXN"]
    }
  }
}

error

object

required

The error envelope. Present on every non-2xx response.

Hide properties

type

string

required

The high-level category of error. Maps deterministically to the HTTP status code (see Error types). Branch on this field first.

code

string

required

A stable, granular identifier for the specific failure (for example parameter_invalid, resource_not_found). Use this for fine-grained handling and user-facing messaging.

message

string

required

A human-readable description of what went wrong. Intended for logs and developers — not for displaying verbatim to end users. Wording may change over time; do not parse it.

param

string

Present on invalid_request_error when a single request parameter is at fault. Names the offending field using dot notation for nested fields (for example address.postal_code).

request_id

string

required

The unique identifier of the request, mirroring the X-Request-Id response header. Include this when contacting support.

details

object

Optional, error-specific structured context (for example allowed values, conflicting key, or rate-limit metadata). The shape depends on the code; treat it as additive.

Only type, code, request_id, and the overall envelope shape are part of the API contract. The message text and the contents of details may evolve — never branch on message, and treat details as best-effort.

Error types

The type field maps one-to-one to an HTTP status code. This is the most reliable signal for deciding your retry and recovery strategy.

`type`	HTTP status	Meaning	Safe to retry?
`invalid_request_error`	`400`	The request was malformed, missing a required parameter, or a value failed validation.	No — fix the request first.
`authentication_error`	`401`	No API key was provided, or the key is invalid or revoked.	No — fix credentials.
`authorization_error`	`403`	The key is valid but not permitted for this surface or resource.	No — use a key with the right scope.
`not_found_error`	`404`	The requested resource does not exist or is not visible to your key.	No.
`conflict_error`	`409`	The request conflicts with the current state (for example a concurrent in-flight duplicate).	Yes, after a short backoff.
`idempotency_error`	`409`	An `Idempotency-Key` was reused with a different request body.	No — use a fresh key or the original body.
`rate_limit_error`	`429`	Too many requests for this key on this surface.	Yes — honor `Retry-After`.
`api_error`	`500`	An unexpected error occurred on Chataigne’s side.	Yes, with exponential backoff.

As a rule of thumb: 4xx errors (except 409 and 429) indicate a problem with your request that you must fix before retrying. 409, 429, and 5xx are transient and safe to retry with backoff.

Error codes

code narrows down type to a specific, stable cause. New codes may be added over time, so always provide a fallback path keyed off type.

`invalid_request_error` (400)

`code`	When it happens
`parameter_missing`	A required parameter was omitted. `param` names the field.
`parameter_invalid`	A parameter was present but failed validation (wrong type, format, or unsupported value). `param` names the field.
`parameter_unknown`	An unexpected parameter was sent. `param` names the field.
`parameters_exclusive`	Two mutually exclusive parameters were sent together (for example `starting_after` and `ending_before`).
`idempotency_key_missing`	A resource-creating `POST` was sent without the required `Idempotency-Key` header.

`authentication_error` (401)

`code`	When it happens
`api_key_missing`	No `x-api-key` header was provided.
`api_key_invalid`	The provided key is malformed, unknown, or revoked.

`authorization_error` (403)

`code`	When it happens
`api_key_wrong_surface`	An admin key (`ch_admin_…`) was used on `/v1`, or an org key (`ch_org_…`) was used on `/admin/v1`.
`session_not_allowed`	A dashboard session was used against the `/v1` or `/admin/v1` API.
`permission_denied`	The key is valid for the surface but not authorized for the target resource.

`not_found_error` (404)

`code`	When it happens
`resource_not_found`	The resource does not exist, or your key cannot see it.
`route_not_found`	The HTTP method and path do not match any known endpoint.

`conflict_error` (409)

`code`	When it happens
`request_in_flight`	A concurrent request with the same `Idempotency-Key` is still being processed. Retry after a brief delay.
`resource_conflict`	The request conflicts with the current state of the resource.

`idempotency_error` (409)

`code`	When it happens
`idempotency_key_reused`	The `Idempotency-Key` was previously used with a different request body. `details.original_request_id` references the first request.

`rate_limit_error` (429)

`code`	When it happens
`rate_limit_exceeded`	You exceeded the request quota for this key on this surface. Honor the `Retry-After` header.

`api_error` (500)

`code`	When it happens
`internal_error`	An unexpected error occurred on our side. Retry with exponential backoff; if it persists, contact support with the `request_id`.

The `param` field

For invalid_request_error responses caused by a single field, the envelope includes param — the exact path to the offending parameter. This lets you map the error straight to a form field or request property without parsing message. Nested fields use dot notation, mirroring the request body:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "name is required.",
    "param": "name",
    "request_id": "req_J3kP9vTq1m"
  }
}

param is only present on invalid_request_error. Errors that are not tied to a specific field (authentication, not found, rate limits, server errors) omit it.

Request IDs

Every response — successful or not — carries an X-Request-Id header. On errors, the same value is mirrored into error.request_id. Log it for every request: it is the fastest way for Chataigne support to locate what happened.

curl -i https://server.chataigne.ai/v1/locations/loc_does_not_exist \
  -H "x-api-key: ch_org_..."

HTTP/1.1 404 Not Found
X-Request-Id: req_8sQx2pL0aZ
Content-Type: application/json

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "No location found with id loc_does_not_exist.",
    "request_id": "req_8sQx2pL0aZ"
  }
}

You can supply your own correlation value via the x-request-id request header and we will echo it back, which makes it easy to trace a request across your systems and ours.

See Request IDs for the full lifecycle.

Errors specific to other features

A few behaviors surface as errors but are governed by dedicated features:

Idempotency

Reusing an Idempotency-Key with a different body returns idempotency_error (409). A concurrent duplicate returns conflict_error (409). Keys are retained for 24 hours.

Rate limits

Limits are per-key, per-surface. 429 responses add a Retry-After header alongside the X-RateLimit-* headers.

Authentication

Missing keys return 401. Using a key on the wrong surface — or a dashboard session on the API — returns 403.

Pagination

Sending starting_after and ending_before together returns invalid_request_error with code parameters_exclusive.

Handling errors

A robust client should:

Branch on error.type (via the HTTP status) to choose a strategy: fix the request, refresh credentials, or retry.
Use error.code for fine-grained handling and to map to user-facing messaging.
Surface error.param to point users at the exact field to correct.
Retry only transient errors — 409, 429, and 5xx — with exponential backoff, and honor Retry-After on 429.
Always log error.request_id so failures are traceable.

# Inspect both the status code and the body. -f is intentionally NOT used so
# the error envelope is printed instead of being swallowed by curl.
curl -sS -w "\nHTTP %{http_code}\n" \
  https://server.chataigne.ai/v1/organizations/org_8sQx2pL0aZ/locations \
  -H "x-api-key: ch_org_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "name": "Pizzeria Bellini", "currency": "ZZZ" }'

# => HTTP 400
# {
#   "error": {
#     "type": "invalid_request_error",
#     "code": "parameter_invalid",
#     "message": "currency must be one of CHF, EUR, GBP, BRL, USD, MXN.",
#     "param": "currency",
#     "request_id": "req_8sQx2pL0aZ"
#   }
# }

Retrying a POST is only safe when you reuse the same Idempotency-Key across attempts. Generating a new key per attempt can create duplicate resources. Generate the key once per logical operation, before the first attempt.

​The error envelope

​Error types

​Error codes

​invalid_request_error (400)

​authentication_error (401)

​authorization_error (403)

​not_found_error (404)

​conflict_error (409)

​idempotency_error (409)

​rate_limit_error (429)

​api_error (500)

​The param field

​Request IDs

​Errors specific to other features

Idempotency

Rate limits

Authentication

Pagination

​Handling errors

The error envelope

Error types

Error codes

`invalid_request_error` (400)

`authentication_error` (401)

`authorization_error` (403)

`not_found_error` (404)

`conflict_error` (409)

`idempotency_error` (409)

`rate_limit_error` (429)

`api_error` (500)

The `param` field

Request IDs

Errors specific to other features

Handling errors