Skip to main content

​
The envelope

All errors share the same JSON shape: 
{
  "error": "machine_readable_code",
  "message": "Human-readable explanation",
  "request_id": "req_abc123…",
  "...": "additional context fields where useful"
}
error is a stable string suitable for branching in your code. message is human-readable and may change wording across releases. request_id matches the X-Request-Id header on the response.

​
HTTP status codes

StatusMeaningExamples
200SuccessNormal response
201CreatedAfter POST /v1/payment-links
400Bad requestInvalid JSON, missing required field
401UnauthorisedMissing or invalid API key
402Payment Requiredx402 / MPP / AP2 challenge response
403ForbiddenKey lacks the required scope
404Not foundUnknown checkout token, unknown resource
409ConflictDuplicate idempotency key, double-spend on a tx_id
422UnprocessableSchema is valid but the action can’t proceed (e.g. KYC required for mainnet)
429Too many requestsRate-limited. See Rate limits.
5xxServer errorGateway, facilitator, or upstream chain RPC unavailable

​
Common error codes

CodeWhenHTTP
invalid_api_keyBearer token is missing or doesn’t match a known key401
tenant_id_mismatchThe X-Tenant-Id header doesn’t match the key’s tenant403
kyb_required_for_mainnetTrial tenant tried a live network422
payment_link_expiredCustomer tried to verify a checkout past its TTL422
payment_link_already_paidSame checkout verified twice409
payment_not_verifiedFacilitator couldn’t confirm the on-chain transaction422
self_payment_blockedPayer address equals payout address403
unsupported_networkThe chain isn’t enabled for this tenant400
cross_tenant_replayTx ID already used by a different tenant422
rate_limitedPer-tenant or per-IP rate limit hit429

​
Behaviour expectations

  • 4xx errors indicate a problem the caller can fix. Don’t retry without changing something.
  • 5xx errors are server-side. The client should retry with backoff. Default Retry-After is 30 seconds.
  • 402 challenges are not errors per se. They’re the start of an x402 / MPP / AP2 payment flow. See the protocol pages.

​
See also