Errors and limits

What errors look like, the common codes, and the rate limits.

Error shape

Every error is JSON with a stable error code. Some add a detail in plain words, and validation errors list issues.

{ "error": "invalid_request", "issues": [{ "code": "too_small", "message": "String must contain at least 3 character(s)", "path": ["request"] }] }

Common codes

StatuserrorMeaning
400invalid_requestThe body failed validation; see issues.
403bad_signatureThe signature doesn't verify against the mandate's key.
403agent_blockedThe store's rules refuse this agent; detail says why.
404not_foundNo such order, mandate or request.
409purchase_already_openThe mandate already has a live purchase; orderId names it.
409not_undoableThe order isn't held or captured any more, for example it was already voided.
409order_changed_retryThe order changed while this request ran. Read it again and retry.
413photo_too_largeThe photo is over 4 MB.
422open_questions, missing_budgetThe draft can't be signed yet; mustAsk lists what's missing.
422stale_requestrequestedAt is more than 15 minutes from the server's clock.
422no_compliant_productNothing in the catalog fits the mandate; considered lists what was checked.
422mandate_does_not_match_requestThe signed mandate differs from the request the agent made.
429rate_limitedToo many requests, or a free-tier budget is spent. Wait Retry-After seconds.
502paypal_checkout_failed, undo_failed, channel3_errorPayPal or the catalog failed. Safe to retry.
503ai_unavailable, parser_unavailableThe AI model is unavailable. Try again shortly.

Rate limits

Limits are per visitor, over sliding windows. A 429 response carries a Retry-After header and a retryAfter field in seconds.

WhatPer minutePer hour
Drafting a mandate630
Shopping inside a mandate420
Product search1060
Undo630
MCP tool calls60600
Changing the store's rules1060

The AI model and the product catalog also have daily and monthly budgets shared by everyone. When one is spent, those endpoints return 429 until it resets.

Retries

Every money call to PayPal carries a fixed PayPal-Request-Id per order, so retrying a void, capture or refund never moves money twice.

On this page