API

Errors

Status codes, error codes and how to retry.

Errors use HTTP status codes and a JSON body with a stable machine-readable code:

json

{
  "version": 1,
  "error": {
    "code": "conflict",
    "message": "A newer result was saved. Fetch its manifest again."
  }
}

Read error.code in code and show error.message to people. Messages can change; codes do not. A few admission conflicts on Create a thread answer with a plain-text message instead of this body; check the status first.

Codes

Status	Code	Meaning	Retry?
400	`invalid_request`	The request is malformed or fails validation.	Fix the request.
401	`unauthorized`	The token is missing, invalid or revoked.	Use a valid token.
402	`forbidden`	Billing is not set up, or the account is out of credits.	Add credits.
403	`forbidden`	The token lacks the scope, the account is suspended, or the command is not allowed for tokens.	No.
404	`not_found`	The resource does not exist or is not yours.	No.
409	`conflict`	The request disagrees with current state: a reused id with a different body, a stale execution, a newer result.	Read the current state, then decide.
413	`invalid_request`	The body is too large.	Send less.
502, 503	`unavailable`	A dependency did not answer.	Yes, with backoff and the same body.

Resources outside your account answer 404, never 403, so a token cannot probe other accounts.

Safe retries

Create a thread: retry with the same taskId and an identical body; you get the same thread. A different body with the same taskId is a 409.
Send a message: read the thread first and send with its current execution.id. A 409 means the execution changed or the thread cannot take the message now; read it again before retrying.
Download the result archive: a 409 means a newer result replaced the one you asked for; read the manifest again.

curl --fail-with-body exits non-zero on any of these and prints the body, so scripts never mistake a rejected message for success.