Errors

Every error response has the same shape:

{
  "error": "the collection 'orders' does not exist",
  "code": "COLLECTION_NOT_FOUND",
  "status": 404,
  "detail": "collection: orders",
  "retryable": false,
  "next_action": "refresh_resource",
  "fix": {
    "operation": "collection.list"
  }
}

Branch on code, never on error's text: the message can change without notice, the code cannot. Read retryable and next_action to decide the next request instead of pattern-matching the error family from the code's name.

Code families

Codes are grouped by a 4-hex-digit range so a mask (code & 0xF000) answers the family without a string compare.

Retry guidance

retryable: true appears only for a transient condition: a transaction conflict, rate limiting, a concurrency limit, server load or a timeout. Retry those within your own deadline, with backoff; preserve the request's idempotency key so a retried write is not applied twice.

Do not retry a non-retryable error by resending the same request. A validation error (INVALID_ARGUMENT), a permission error, a schema violation or an unsupported operation fails the same way every time until you change the request. A write guarded by an expected version (if: { _version }) that lost a race needs a fresh read before the next attempt, not a blind retry.

Next-operation hints

fix.operation names the call most likely to resolve a failure, independent of the error text. A *_NOT_FOUND error for a collection, function, account member, API key or thread points at that resource's list operation, so a caller refreshes its view of what exists before trying again. Call the operation fix names (an MCP tool by fix.tool, a CLI command by fix.cli, or the HTTP method and path) rather than guessing a listing endpoint from the resource name.

Every typed error code, its hex value, HTTP status and message are listed below.

Every error code

The code of a failed call is one of these names. The status is the HTTP status the call answers with. Where a follow-up call resolves the error whatever operation raised it, it is listed.