Errors

One error envelope, stable codes, and what to do about each.

Every failing API response uses the same shape. Branch on code, which is stable, rather than on message, which is written for humans and may change.

Error response

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": { "messages": ["Array must contain at least 1 element(s)"] }
  }
}

Codes

Code	Status	What to do
bad_request	400	The request was malformed, for example invalid JSON. Fix and retry.
unauthorized	401	Authenticate. Check the key was not revoked.
forbidden	403	The credential is valid but not allowed to do this.
not_found	404	No such resource in this workspace.
conflict	409	The write collided with an existing record, such as a duplicate email.
validation_error	422	Read `details` for the offending fields.
rate_limited	429	Back off and retry; the message says for how long.
unavailable	503	A dependency is down. Retry with backoff.
internal_error	500	Something broke on our side. Safe to retry once.

Errors mid-stream

A request that has already returned 200 cannot change its status. If generation fails after the stream opens, an error event arrives inside the stream, followed by done with finishReason: "error".

Codes#

Codes