Errors - Peachdesk AI

Unlike the rest of the PeachDesk API (which uses a detail field — see API Errors), the BRAHMA v1/* routes return errors in the OpenAI error format, so OpenAI SDKs raise their native typed exceptions unchanged.

Error envelope

Every non-2xx response from the BRAHMA routes has this shape:

{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Field	Type	Description
`message`	string	Human-readable description of what went wrong
`type`	string	Error class — e.g. `invalid_request_error`, `tokens`, `requests`, `server_error`
`param`	string or null	The request parameter at fault, when one can be identified
`code`	string or null	Machine-readable code — e.g. `invalid_api_key`, `model_not_found`, `rate_limit_exceeded`

Status codes

Status	`type`	`code`	Meaning
`401`	`invalid_request_error`	`invalid_api_key`	Missing or invalid `X-API-Key`
`404`	`invalid_request_error`	`model_not_found`	The requested model id does not exist
`429`	`tokens` or `requests`	`rate_limit_exceeded`	TPM or RPM limit exceeded — see Rate Limits
`5xx`	`server_error`	—	Unexpected server-side failure

Request IDs

Every BRAHMA response — success or error — carries an x-request-id header of the form req_<hex>:

x-request-id: req_9f0c2a4d7b1e

Log it with your requests, and quote it in support requests so the exact request can be traced.

Handling errors

Retry 429 with exponential backoff and jitter, honoring the retry-after header — see Rate Limits.
Retry 5xx with exponential backoff — transient server errors can resolve on retry.
Do not retry 401 or 404 — these indicate problems with your request that will not self-resolve.
Branch on code, not message — messages are human-readable and may change; codes are stable.