Errors and retries
API errors use a consistent format. The code is for application logic; the message explains the issue. Keep user input intact and offer a clear next step.
On this page
One error format#
Responses do not include stack traces, SQL, tokens or a full external provider response. Do not display raw internal logs to a customer.
{
"error": {
"code": "GATEWAY_NOT_CONNECTED",
"message": "Financial operations are temporarily unavailable. Try later or contact support."
}
}Common error groups#
| HTTP | Examples | Next step |
|---|---|---|
| 400 | INVALID_JSON, UNKNOWN_FIELD, INVALID_INPUT | Check input and allowed fields |
| 401 | AUTH_REQUIRED, SESSION_EXPIRED | Sign in again |
| 403 | INVALID_ORIGIN, CSRF_REQUIRED | Check origin and current session |
| 404 | NOT_FOUND, TICKET_NOT_FOUND | Check the address and ownership |
| 409 | CHALLENGE_UNAVAILABLE | Start a new sign-in |
| 410 | CHALLENGE_EXPIRED | Create a new sign-in link |
| 413 | REQUEST_TOO_LARGE | Reduce the request body |
| 415 | JSON_REQUIRED | Send application/json |
| 429 | RATE_LIMITED | Reduce frequency and wait |
| 503 | GATEWAY_NOT_CONNECTED, SERVICE_UNAVAILABLE | Check availability or try later |
Rate limits#
| Action | Limit |
|---|---|
| Start sign-in | 6 per minute per hashed address |
| Check a challenge | 90 per minute per challenge |
| Knowledge question | 12 per minute per hashed address with D1 |
| Create a server link | 20 per minute per user |
| Merchant API | 90 requests per minute per key |
| New application | Five per day per user |
| Resume application / moderator decision | 30 per minute per user for each action |
| AI website review | 30 per hour service-wide |
| Read checkout or attempt payment | 90 per minute per hashed address |
| Create a support request | 6 per hour per user |
| Test a notification | 3 per hour per user |
| AI generation | 60 per hour service-wide by default |
What can be retried#
A read can be retried after a delay on a temporary network failure. Before retrying a mutation, check whether the original completed; a lost response does not prove failure.
Financial operations require idempotency and a server status check. A client redirect to a result page is not a substitute for confirmation.
What to include in a request#
- The page and action immediately before the error.
- Time, time zone and the visible error code.
- Your invoice or support-request reference, if available.
- A short description of the result you expected.