ApiError. There is exactly one shape, and it is a transcription of the server’s error envelope — the client uses only the server’s codes, so the two can never disagree. The client makes an ApiError itself in two cases: an error body that is not the envelope, and a 2xx body it cannot read.
The ApiError class
The specific machine code, e.g.
validation_failed, subscription_required, insufficient_credits.The server’s correlation id for this call — quote it in a bug report; it is the single most useful field.
Catching
An error body that is not the envelope
Something in front of the API (a proxy or the network edge) can answer with an HTML page or plain text instead of the JSON envelope. The client then picks thecode from the HTTP status, using only codes from the server’s taxonomy:
The
message is fixed, HTTP <status>: the error response had no readable details, and never quotes the page. A 403 is the exception: the API answers every 403 with the envelope, so a bare one was blocked before it reached the API, and the message says so. requestId is the x-request-id header when there is one, otherwise "".
A response this SDK cannot read
A 2xx body that does not match the SDK’s schema (an SDK older or newer than the API) throwsResponseParseError, a subclass of ApiError. It has the real status (a 2xx), code: "internal_error", the requestId, and three more fields. Its status means the call landed: don’t forward it as an HTTP status, and don’t retry a write on it, or it runs twice. Check instanceof ResponseParseError before treating an ApiError as a refusal.
What the client does not do
- No retries. A caller that wants retries owns that decision — the CLI and the dashboard want different policies. A
429or5xxis thrown like any other error. - No code → status table.
typeandstatusare read off the response. The server owns that mapping; a second copy here would be a second taxonomy that could drift.
Errors worth planning for
The full catalogue lives in the API error reference.