Errors

The API returns conventional HTTP status codes. 2xx means success; 4xx means the request was invalid and you can probably fix it by changing your input; 5xx means something went wrong on our side — the request is safe to retry with backoff.

Error shape

Errors share a consistent envelope so generic handling works across every endpoint.

400 Bad Request

{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "Parameter `cursor` is required when `has_more` was true.",
    "param": "cursor",
    "request_id": "req_01J6…"
  }
}

Include request_id when reaching out to support — it lets us find the failing request in our trace index instantly.

Status code reference

Status	Meaning
`200 OK`	Request succeeded.
`201 Created`	Resource created.
`400 Bad Request`	The request body or parameters were invalid.
`401 Unauthorized`	Missing or expired access token.
`403 Forbidden`	Token valid but lacks the required scope.
`404 Not Found`	Resource doesn't exist (or you can't see it).
`409 Conflict`	Write collided with another concurrent change.
`422 Unprocessable`	Request validated structurally but failed a business rule.
`429 Too Many Requests`	Rate limit exceeded. Back off and retry.
`5xx`	Server error. Safe to retry with exponential backoff.

Retrying

For 5xx and 429 responses, retry with exponential backoff capped at 30 seconds. Our SDKs do this automatically.

Built-in retry

const aleta = new Aleta({
  clientId,
  clientSecret,
  maxRetries: 5,
});

Idempotency keys let you safely retry POST requests without creating duplicates. Supply Idempotency-Key: <uuid> on any mutating request.