Error codes
A stable, machine-readable error catalog. Codes are never removed or reused, and HTTP status always follows semantics.
Catalog
Common public error codes, their HTTP status, and whether a client should retry them automatically.
| Code | HTTP | Retryable | Meaning |
|---|---|---|---|
INSUFFICIENT_CREDIT | 402 | No | Wallet balance is below the call's cost. Top up or enable auto-recharge. |
WALLET_CAP_EXCEEDED | 402 | No | Wallet has reached its balance cap. Spend down, or upgrade your plan. |
PRO_REQUIRED | 402 | No | This feature or module requires the Pro plan. |
KYC_REQUIRED | 402 | No | Monthly top-up has crossed the threshold that requires identity verification. |
TOPUP_2FA_REQUIRED | 402 | No | A large top-up triggered email 2FA; retry with the challenge token and code. |
BYOK_TRIAL_EXPIRED | 402 | No | The 30-day BYOK trial has ended; upgrade to Pro to keep using your own keys. |
UNAUTHORIZED | 401 | No | Missing or invalid project key. |
SCOPE_INSUFFICIENT | 403 | No | The project key's scope does not include this capability. |
KEY_REVOKED | 403 | No | The project key has been revoked; use a new key. |
MODULE_NOT_AVAILABLE_IN_REGION | 403 | No | This module is not available in the current region SKU. |
IDEMPOTENCY_KEY_REQUIRED | 400 | No | Resource-creation calls must include an idempotency_key. |
IDEMPOTENCY_CONFLICT | 409 | No | The same idempotency_key was reused with different parameters. |
RATE_LIMIT_USER | 429 | Auto-retry | Per-user rate limit reached; wait for Retry-After or upgrade for higher quota. |
RATE_LIMIT_IP | 429 | Auto-retry | Per-IP rate limit reached; wait for Retry-After. |
VENDOR_QUOTA_EXCEEDED | 429 | Auto-retry | Upstream vendor quota is exhausted; the gateway fails over to another vendor automatically. |
VENDOR_DOWN | 503 | Auto-retry | Upstream vendor is down and failover did not succeed. |
VENDOR_TIMEOUT | 503 | Auto-retry | Upstream vendor exceeded the timeout; the call is retried. |
MAINTENANCE | 503 | Auto-retry | Planned maintenance window; wait for Retry-After. |
UNKNOWN_ERROR | 500 | No | An unrecognized error code (forward compatibility); surfaced as-is to your code. |
Handling errors
By default a failed call returns a result with an error instead of throwing, so your business flow is never interrupted.
Rate-limit and upstream errors are retried automatically with backoff, honoring the Retry-After header.
Published error codes are permanent: their meaning never silently changes, and deprecated codes keep returning for at least 12 months.