Errors - Chataigne Docs

The Chataigne API uses conventional HTTP status codes and returns a structured JSON body when a request fails.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "currency must be one of CHF, EUR, GBP, BRL, USD, or MXN.",
    "param": "currency",
    "request_id": "req_9c4a1e22"
  }
}

Error fields

string

Broad category suitable for programmatic handling.

string

Stable reason within the category.

string

Human-readable explanation for developers. Do not branch application logic on this text.

string | null

Request field associated with the failure, when applicable.

string

Identifier used to trace the request. It matches the X-Request-Id response header.

Status codes

Status	Error type	Meaning	Retry?
`400`	`invalid_request_error`	The request or one of its parameters is invalid.	No; correct the request.
`401`	`authentication_error`	The API key is missing or invalid.	No; correct the credential.
`403`	`authorization_error`	The key’s scope or permissions do not allow the action.	No; use appropriate access.
`404`	`not_found_error`	The resource does not exist or is unavailable to the key.	No; verify the ID and scope.
`409`	`conflict_error` or `idempotency_error`	The request conflicts with current state or idempotency rules.	Depends on the code.
`429`	`rate_limit_error`	The key exceeded its request limit.	Yes, after `Retry-After`.
`500`	`api_error`	Chataigne could not complete the request.	Yes, with bounded backoff.

Recommended handling

Branch on the HTTP status, then on error.type and error.code when needed.
Show validation feedback near error.param when it is present.
Retry only transient failures (429 and selected 5xx responses), with exponential backoff and jitter.
Log error.request_id with your own operation identifiers, without logging the API key or unnecessary customer data.
Include the request ID when contacting Chataigne support.

Node.js

const response = await fetch('https://server.chataigne.ai/v1/locations', {
  headers: { 'x-api-key': process.env.CHATAIGNE_API_KEY },
});
const body = await response.json();

if (!response.ok) {
  console.error({
    status: response.status,
    type: body.error?.type,
    code: body.error?.code,
    requestId: body.error?.request_id,
  });
  throw new Error(body.error?.message ?? 'Chataigne API request failed');
}

See Request IDs, Rate limits, and Idempotency for retry-related details.

​Error fields

​Status codes

​Recommended handling

Error fields

Status codes

Recommended handling