Error Codes
The status codes the API returns, and the shape of an error.
| Code | Meaning |
|---|---|
| 400 | Bad Request (malformed JSON bodies return { success: false, error: "Invalid JSON in request body" }) |
| 401 | Unauthorized - Missing or invalid API key |
| 402 | Insufficient credits |
| 403 | Forbidden - Wallet does not match resource owner. A NON-JSON 403 comes from the CDN/WAF, not the API — usually a generic programmatic User-Agent; send a descriptive one (see authentication.userAgent). |
| 404 | Not Found |
| 410 | Gone - Invoice expired |
| 429 | Too Many Requests - Rate limit exceeded (Retry-After + X-RateLimit-* headers, retryAfter in body; see rateLimits) |
| 500 | Internal Server Error |
Error body
JSON: { success: false, error: string, ... }. error is either a short human-readable sentence OR a stable UPPER_SNAKE code for machine matching (e.g. ACCOUNT_NOT_FOUND) — whenever it is a code, a message field carries the human sentence. Bodies may add context fields (retryAfter, docs, hint, balance). requestId (mirroring the x-request-id response header) is included on gateway-level errors — quote it in support requests.