Errors and retries

What each failure means, and whether to retry with the same idempotency key.

Failure	What to do	Idempotency key
Over the budget cap (`budget_limit_reached`; inference returns `payment_declined`)	Ask an org admin to raise the cap, then pay again	New
Merchant not active or not on the allowlist	Pick another merchant	n/a
Inference provider not on the allowlist (`payment_declined`)	Add the provider to the budget’s allowlist	New
Merchant returned a 5xx	Retry	Same
Daily cap reached	Wait for the next UTC day	n/a
Agent is paused	Its owner resumes it from the agent page	Same
HTTP 429	Wait for `Retry-After`, then retry	Same

An over-budget payment is declined, with no approval path, so don’t poll for one. See Over budget. For the daily cap, see Limits. To resume a paused agent, see Pause or revoke an agent.

Payment failures

Verdict	What it means	What to do
Compliance mismatch	Merchant not on allowlist or inactive	Pick a different merchant
Spending mismatch	Over the budget cap	Declined with no approval path: a fixed-price payment with `budget_limit_reached`, and a metered payment whose per-request maximum exceeds the remaining budget with its own decline reason. Once an org admin raises the cap, send a new payment with a new idempotency key (see Over budget)
Daily cap reached	Hard reject, no approval path	Wait for the next UTC day. See Limits
Agent deactivated	Hard reject, no approval path	See Pause or revoke an agent
Account locked or frozen	Hard reject, no approval path	Contact Anchorage support — resolution requires staff action
Insufficient account balance	Hard reject, no approval path	Fund the account, then retry
Resource mismatch	The merchant’s quote names a resource at a different address (host or port) than the URL actually reached	Hard reject, no approval path. The merchant endpoint is misconfigured; pick a different merchant
Schema mismatch	Request body doesn’t match the merchant’s published schema	Fix the request body and retry with a new idempotency key
Key already used with another protocol	A repeat call met a different payment protocol than the original payment used; nothing new was paid	Check the named payment’s status. Before you use a new idempotency key, confirm with Anchorage support that it did not settle: a pending, declined, or expired payment can still turn out to have paid
Upstream 5xx	Merchant indeterminate	Retry with the same idempotency key — repeat calls collapse to one settlement
Interrupted while signing	The payment stopped before an authorization was recorded; reserved funds stay held	Retry with the same idempotency key — contact Anchorage support if retries keep failing

Inference failures

Every error these inference endpoints return once they accept a request is an OpenAI-compatible JSON body, {"error": {"message", "type", "code"}}, so an OpenAI SDK or a client built on one shows error.message to the user as-is: POST /v1/chat/completions, GET /v1/models, the image, video, and audio generation routes, and their status polls. POST /v1/messages returns the same errors in Anthropic’s shape, covered in Anthropic Messages API. POST /v1/decide keeps its own error shape, covered in Typed judgments. Three kinds of request are rejected before they reach an inference endpoint, with a non-JSON body instead: an HTTP method the route doesn’t serve gets 405 Method Not Allowed, except on /v1/messages, which answers in its own JSON error shape; a request whose declared Content-Length is over 2 MiB gets 413 Request Entity Too Large, except a POST to an inference endpoint that takes POST, which refuses an oversized body in its own JSON error shape; and an unsafe browser request from another site, such as a cross-site POST, gets 403 Forbidden. These non-JSON responses carry no error.code and no x-should-retry, so handle them by HTTP status. For every other error, the message says what happened, and the table below says what to do; branch on error.code. Each of those responses also carries x-should-retry: true or false, which the OpenAI SDKs follow when deciding whether to retry on their own. When a payment was submitted, the message names the transaction and the response carries it in X-Transaction-ID, and the message says how to resend the request without paying twice: the identical request, with the same Idempotency-Key if you sent one, and with none added if you didn’t. The message never quotes the model provider’s own error text.

Status	`error.code`	What it means	What to do
401	`invalid_api_key`	No usable agent API key.	Mint or check the key on the agent’s page.
400	`invalid_request`	The request body couldn’t be read, is over 1.5 MiB, or its `Idempotency-Key` is over 255 characters. The message says which. Nothing charged.	Fix the request.
400	`streaming_not_enabled`	The request set `"stream": true` on an endpoint that doesn’t stream. Nothing charged.	Send the request with `"stream": false`, or omit the field.
400	`provider_rejected_request`	The model provider rejected the request, for example an unknown model name. When a payment was submitted, the message and `X-Transaction-ID` name it.	Fix the request. `GET /v1/models` lists the model names. If a payment was submitted, check that transaction before retrying.
403	`budget_not_configured`	No spend limit configured.	Configure a budget, then retry. A retry with the `Idempotency-Key` of a request you already paid for goes through to that payment.
402	`budget_approval_required`	A request from before over-budget requests started declining that was left waiting on an admin. It no longer completes, even after approval. A request over the budget cap now returns `payment_declined`.	Send a new request with a new `Idempotency-Key` once the budget allows it.
403	`daily_limit_reached`	The agent reached its daily spending cap. Nothing charged.	Retry after the cap resets.
403	`budget_inactive`	The agent’s budget isn’t active. Nothing is charged unless the message names a transaction.	Activate the budget, then retry. When the message says Anchorage recorded the decline, it names the declined transaction in the message and the `X-Transaction-ID` header, and the identical request is declined again: check the transaction before you send it again.
403	`insufficient_funds`	The account doesn’t have enough funds for this request. Nothing is charged unless the message names a transaction.	Add funds, then retry. When the message says Anchorage recorded the decline, it names the declined transaction in the message and the `X-Transaction-ID` header, and the identical request is declined again: check the transaction before you send it again.
403	`payment_declined`	The payment was declined: a compliance, spending (the budget cap, with a message that the payment would take the budget past its cap), or account-status check, a per-payment or program limit, or a payment the model provider asked for that Anchorage can’t make for this request. The message gives the reason when it’s known. When it gives a reason and names no transaction, nothing was charged. When it says Anchorage can’t confirm whether the payment went through, the payment may have been made. When it says the request matches an earlier payment that used a different payment protocol, it names that payment’s transaction ID in the message and the `X-Transaction-ID` header, and nothing new was paid.	Act on the reason, then retry. For a budget limit, an org admin raises the cap, and you then retry with a new `Idempotency-Key`. When the message says Anchorage recorded the decline, it names the declined transaction in the message and the `X-Transaction-ID` header, and the identical request is declined again: check the transaction before you send it again. When the message can’t confirm the payment, send the identical request again with the same `Idempotency-Key` if you sent one, and with none added if you didn’t: it returns any payment already made instead of paying again. See Payment failures.
503	`platform_unavailable`	A temporary problem on Anchorage’s side stopped the payment. Your budget didn’t cause it. When a payment was submitted, the message and `X-Transaction-ID` name it. Otherwise the message says Anchorage can’t confirm whether the payment went through.	When the response carries `x-should-retry: true`, retry in a few minutes with the identical request and the same `Idempotency-Key` if you sent one, and with none added if you didn’t: it returns any payment already made instead of paying again. When the message names a transaction, the response carries `false`: check that transaction instead, since resending returns the same recorded answer.
409	`payment_request_expired`	The model provider’s payment request expired before Anchorage could pay it. Nothing charged.	Retry the request.
502	`provider_unavailable`	The model provider is unavailable or unreachable. Nothing charged.	Retry in a few minutes.
429	`rate_limit_exceeded`	The model provider is rate limiting requests, or Anchorage is limiting how often new payment destinations can be set up. When a payment was submitted, the message and `X-Transaction-ID` name it.	When the response carries `x-should-retry: true`, wait for the `Retry-After` delay if it has one, otherwise back off, then retry. When a payment was submitted, the response carries `false`: check that transaction instead, since resending can return the same recorded answer.
502	`paid_no_response`	A payment was submitted but no usable completion came back: the provider refused the payment, returned a server error, or returned an answer too large to record. The message and `X-Transaction-ID` name the transaction.	Check that transaction before you send the request again, and resend the way the message says to avoid paying twice. If it stays pending, contact Anchorage support.
403	`origin_not_permitted`	Refused before this endpoint’s own request handling ran (for example, a compliance check on the connection). Nothing charged.	See Payment failures.
500	`internal_error`	Something went wrong on Anchorage’s side.	Retry in a few minutes when the response carries `x-should-retry: true`; when it carries `false`, the same request fails the same way, so contact Anchorage support.
404	`generation_job_not_found`	A generation status poll named no job of this kind that belongs to this agent.	Check the id and the route.

Get started

How-to

Concepts

Reference

Payment failures

Inference failures

​Payment failures

​Inference failures

Payment failures

Inference failures