Errors use HTTP status codes and one JSON shape:
{
"error": {
"type": "invalid_request_error",
"code": "TOOL_DEFINITION_INVALID",
"message": "one or more tool definitions are invalid",
"retryable": false,
"request_id": "req_01jc8w7k2m4p6r8t0v2x",
"details": [
{ "tool": "#3", "code": "INVALID_NAME", "path": "/function/name", "severity": "error", "message": "name must match ^[A-Za-z0-9_-]{1,64}$" }
]
}
}Branch on code, not on message; messages can be reworded. retryable tells you whether the same request might succeed later. request_id matches the X-Request-Id header.
Codes
| Status | Code | Meaning | Retry? |
|---|---|---|---|
| 400 | INVALID_REQUEST | A field is missing or malformed. message says which. | No |
| 400 | UNKNOWN_TOOL_CHOICE | tool_choice names a tool that isn't in the toolset. | No |
| 401 | INVALID_API_KEY | Missing, malformed, wrong or revoked key. | No |
| 402 | INSUFFICIENT_CREDITS | Not enough credits. Top up. | After topping up |
| 403 | FORBIDDEN | The key can't do this. | No |
| 403 | TREE_SLOT_LIMIT_EXCEEDED | Legacy: toolsets are now unlimited. | No |
| 403 | FREE_TIER_TOOL_LIMIT_EXCEEDED | More than 20 tools on the Free plan. | No |
| 403 | FREE_TIER_EDIT_NOT_ALLOWED | Free can't add versions to a toolset. | No |
| 404 | BRICK_NOT_FOUND | No toolset with that id in your account. | No |
| 404 | VERSION_NOT_FOUND, JOB_NOT_FOUND | No such version or build job. | No |
| 409 | BRICK_NOT_READY | The toolset has no ready version yet. | Yes, after the build |
| 409 | BRICK_NAME_CONFLICT | You already have a toolset with that name. | No |
| 409 | VERSION_CONFLICT | base_version isn't the latest version. | After re-reading |
| 409 | ALIAS_CONFLICT | expected_row_version didn't match. | After re-reading |
| 409 | IDEMPOTENCY_CONFLICT | The Idempotency-Key was used with a different body. | No |
| 413 | PAYLOAD_TOO_LARGE, TOO_MANY_TOOLS | Over 1 MiB, or over 10,000 tools. | No |
| 415 | UNSUPPORTED_MEDIA_TYPE | Missing Content-Type: application/json. | No |
| 422 | TOOL_DEFINITION_INVALID | Tools break the rules. details lists each problem. | No |
| 429 | RATE_LIMITED | Over your rate. Wait Retry-After seconds. | Yes |
| 502 | INVALID_ENGINE_OUTPUT | An internal step returned something unusable. | Yes |
| 503 | OVERLOADED, ENGINE_UNAVAILABLE and similar | Temporarily unavailable. Honour Retry-After. | Yes |
| 504 | DEADLINE_EXCEEDED | The request took too long. | Yes |
| 500 | INTERNAL | A bug on our side. | Yes, once |
Retrying well
Retry only when retryable is true. Wait Retry-After seconds when it's set, otherwise back off exponentially from about half a second, and give up after a few tries. Send an Idempotency-Key with requests you retry, so a retry of a request that actually went through isn't charged twice.
Problems inside a tool list
TOOL_DEFINITION_INVALID comes with details, one entry per problem. tool is the tool's name, or #3 (its position, from 1) when the name itself is the problem. path is a JSON pointer inside that tool. The builder in the console shows these next to the right field.