Limits, errors and retries.

This page is for developers, and for owners who read an error their AI client showed them. It lists the limits, explains how to repeat a call safely, and gives every error code with the action to take.

MCP tools and the Agent API share one error format and one set of codes. Over HTTP the codes arrive with an HTTP status. Over MCP a failed tool call returns isError: true, and the same JSON is in the result text, so the model can read it and correct itself.

The error envelope

{
  "error": true,
  "code": "VALIDATION_FAILED",
  "message": "The request data did not pass validation.",
  "retry_strategy": "fix_request",
  "details": {
    "errors": { "card_id": ["The card_id field is required."] }
  }
}

details is optional. Framework errors on agent paths use the same envelope.

Retry strategies

Every error declares what to do next.

For backoff, wait the Retry-After seconds when the answer has them. Otherwise wait longer after each try, for example 1, 2, 4, 8 and 16 seconds, then stop.

Limits

A response to an authenticated request carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 carries Retry-After.

Idempotency

An idempotency key lets you repeat a change without doing it twice. Use it whenever a call might time out.

• Over MCP, every tool that changes data takes a required idempotency_key argument.
• Over HTTP, send an Idempotency-Key header. It is optional.
• Format. 1 to 80 characters from A-Z, a-z, 0-9, hyphen and underscore. A UUID works.
• A new change gets a new key. Generate a fresh random value for each change.
• A retry reuses the key. Repeat the same request with the same key. Reward Loyalty returns the stored answer, and over HTTP it adds Idempotent-Replayed: true. Nothing runs twice.
• A different request under the same key returns 409 IDEMPOTENCY_CONFLICT.
• A request that is still running returns 409 IDEMPOTENCY_IN_PROGRESS with Retry-After: 1. Retry with the same key. A request that stops without finishing releases its key. Only when its process was killed outright does a later call wait 15 minutes to take the key over.
• Only successful answers are stored. That includes a 202 that prepared an approval, so a repeat returns the same approval. If a call fails, the key is released and you can try again, with the same key.
• An idempotency key belongs to one credential and one operation. The same value sent by another connection starts fresh there. Sent again for another record of the same operation, it returns 409 IDEMPOTENCY_CONFLICT.
• A replay is checked again. If the connection has since lost the scope or the plan feature, the replay is refused and nothing is returned.

Reward Loyalty keeps each stored answer for 7 days, encrypted. The scheduled task agent-receipts-retention removes older ones. It runs with the other scheduled tasks and from the Health center, and it needs no queue worker.

Stored-money operations (selling a stored-money pass, spending from it and reversing a spend) and a purchase sent with a source_reference keep their own retry rules. A stored-money operation takes a UUID as its operation key, in the same header or argument. Production checklist covers purchases.

The approval window

A request for approval closes 10 minutes after the AI client prepared it. The owner's decision doesn't extend it. After the owner approves, the AI client must run the change inside the same 10 minutes. See Approvals.

Error codes

Each row gives the code, the HTTP status, the retry strategy and when it happens. A code whose status or strategy differs by case has a row per case, or says so in its row.

Sign-in and access

Request shape

Limits and capacity

Repeated calls

Approval errors

Server and platform

Changes, corrections and records

Counter: points, stamps and vouchers

Email campaigns, store connections and reports

Stored-money passes

Stored-money pass operations (sell_prepaid_pass, spend_pass_money, reverse_pass_money_spend, the pass setup and the money analytics) add the codes below. They arrive in the same envelope. A 422 is fix_request and a 5xx is backoff. A 409 is no_retry, except the conflicts you clear by changing the request (fix_request) and the ones a person must clear (contact_support). The rows below say which. A reused operation key with a different body gets 409 IDEMPOTENCY_CONFLICT with fix_request.

Related topics

• Error handling: the same envelope for the Agent API, with a code-by-code view for HTTP callers.
• Troubleshooting
• Approvals