Errors

Every error of the 221 API (221 Pay, data routes, project routes, including 404 and 405) has the same envelope: a stable code to test in code, a readable message, a request_id to pass to support, fields when fields are rejected, and members specific to the code (limit, reset_at, retry_after_s…), at the same level.

{
  "code": "INVALID_REQUEST",
  "message": "Some fields are invalid.",
  "request_id": "2f6c9a0e-5b1d-4e7f-8c3a-9d0b1e2f3a4c",
  "fields": {
    "customer_phone": "Invalid mobile number for this payment method's country.",
    "offer_code": "offer_code must hold 4 to 16 letters or digits."
  }
}

• Test code, never message or the HTTP status: the text can change, and the same code can carry a different status depending on the route.
• fields groups one message per rejected field, so each error can be shown next to its field.
• message is in French by default; in English with Accept-Language: en or the ?lang=en parameter.
• request_id is also returned in the X-Request-Id header of every response.

Rate limitCopy Anchor Link

600 requests per minute per project. Beyond that: 429 RATE_LIMITED, with the Retry-After header giving the wait in seconds.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

This is the only limit on 221 Pay routes: the daily quota (429 QUOTA_EXCEEDED) covers data routes only. See Authentication, section "Daily quota".

Method not allowedCopy Anchor Link

A /v1 route called with another HTTP method answers 405 with an Allow header, the list of accepted methods, and the same envelope as the other errors, with the code METHOD_NOT_ALLOWED. The message follows Accept-Language (French by default, English when the value starts with en).

HTTP/1.1 405 Method Not Allowed
Allow: GET, POST
Content-Type: application/json

{"code": "METHOD_NOT_ALLOWED", "message": "Method not allowed. Allowed methods: GET, POST.", "request_id": "2f6c9a0e-5b1d-4e7f-8c3a-9d0b1e2f3a4c"}

CodesCopy Anchor Link

Data and project route codesCopy Anchor Link

These codes, upper case like the others, come from the data routes, keys, webhooks and a project's team. The members specific to the code sit at the top level of the body, next to message. The HTTP status can vary by route: test code.

The /auth routes (sign-in, password) also answer with a flat code, message and request_id shape (also in the X-Request-Id header). Their codes are those of the sign-in service, for example INVALID_EMAIL, INVALID_EMAIL_OR_PASSWORD or VALIDATION_ERROR (unreadable body, with a single generic message). TOO_MANY_REQUESTS adds retry_after_s and the X-Retry-After header.

Retry safelyCopy Anchor Link

POST /v1/payments, POST /v1/refunds and POST /v1/payouts require Idempotency-Key: a retry never creates a second operation. See Payments, section "Unknown outcome".

Report an incidentCopy Anchor Link

Send 221 the request_id, the time of the call and the route called. Never the API key or the webhook secret.