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. The error message can change without notice, while the code is stable. Use retryable and next_action to choose the next request instead of inferring it from the code's name.

Code families

Codes are grouped by a four-hex-digit range. A mask (code & 0xF000) identifies the family without a string comparison.

Retry guidance

retryable: true appears only for a transient condition, such as a transaction conflict, rate limit, concurrency limit, server load, or timeout. Retry within your 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), permission error, schema violation, or unsupported operation requires a change to the request. If a write guarded by an expected version (if: { _version }) conflicts with another write, read again before the next attempt.

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 to that resource's list operation. Use it to refresh your view of what exists before trying again. Call the operation named by fix, using fix.tool for MCP, fix.cli for the CLI, or the HTTP method and path.

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

Every error code

A failed call returns one of these names in code, along with the HTTP status shown here. A follow-up operation is listed when it resolves the error regardless of which operation raised it.