Documentation
When a request does not go to plan
Clear inputs, careful request identity, and honest outcomes. The essentials for building with this gateway.
A timeout is not proof of failure
The operation may already have run before the response was lost. Do not automatically replay paid POSTs with a new identity. Inspect Usage and retain the original Idempotency-Key.
| HTTP | Code | What to do |
|---|---|---|
| 400 | INVALID_PARAM | Check the documented field locations, required values, types and limits for this operation. |
| 401 | AUTH_FAILED | The key is missing, invalid, expired or revoked. Do not expose it in logs. |
| 402 | INSUFFICIENT_CREDITS | Your available wallet balance cannot cover this request. |
| 403 | SCOPE_DENIED | Use a key explicitly scoped to this operation. |
| 403 | ACCOUNT_FROZEN | New billable requests are blocked. Review account and payment state. |
| 409 | IDEMPOTENCY_CONFLICT | The identity was already used with different inputs; do not mutate an existing intent. |
| 429 | RATE_LIMITED / CONCURRENCY_LIMIT | Respect Retry-After. Preserve the original request identity. |
| 503 | NOT_CONFIGURED / OPERATION_DISABLED | The service or operation is unavailable. Check the operation’s current availability on its API page. |
Reserved, charged and released are not interchangeable
A request can reserve credits while the result is pending. Confirmed success settles the reservation; confirmed failure releases it. An uncertain result can remain reserved for reconciliation. The available balance is distinct from the ledger balance; do not infer a successful charge from a temporary reservation.
Keep evidence, not secrets
For support, retain the request ID, operation, timestamp and error code. Do not include a raw API key, session cookie, payment secret or unredacted personal input. SERVICE_UNAVAILABLE and SERVICE_BUSY describe conditions on the service side, not your wallet balance.