Errors

Errors use standard HTTP status codes and a consistent JSON shape:

{ "error": { "code": "invalid_request", "message": "Provide `text` or a non-empty `thread`." } }

Status codes

Status	Code	Meaning
`400`	`invalid_request`	A parameter is missing or invalid.
`401`	`unauthorized`	Missing, invalid, or revoked API key.
`403`	`forbidden`	The key lacks the required scope.
`404`	`not_found`	The resource doesn’t exist (or isn’t yours).
`429`	`rate_limited`	Too many requests — see Rate limits.
`500`	`internal_error`	Something went wrong on our side.

4xx errors are safe to surface to your users after fixing the request. Retry 429 and 5xx with backoff.