See Error concepts for how to handle errors idiomatically. This page is the complete code table.
Error envelope
{
"error": {
"type": "validation_error",
"code": "email_invalid",
"message": "...",
"param": "email",
"requestId": "req_01HX3ZE..."
}
}
By status code
400 validation_error
code | Meaning |
|---|
field_required | Required field missing. See param. |
field_too_long | param exceeded max length. |
field_too_short | param below min length. |
enum_invalid | param isn’t an allowed value. |
email_invalid | Not a valid email. |
phone_invalid | Not a valid E.164 phone. |
url_invalid | Not a valid URL. |
currency_invalid | Unsupported currency code. |
amount_too_small | Below minimum charge amount. |
amount_too_large | Above maximum allowed for this tier. |
idempotency_key_reuse | Key used with a different body. |
idempotency_key_conflict | Key in use by a concurrent request. |
cursor_expired | Pagination cursor older than 24 hours. |
401 authentication_error
code | Meaning |
|---|
key_missing | Missing x-api-key or x-api-secret. |
key_invalid | Key pair not recognized. |
key_revoked | Key pair was revoked. |
signature_invalid | Webhook signature check failed. |
403 permission_error
code | Meaning |
|---|
key_forbidden | Key lacks the required scope. |
tenant_suspended | Tenant has been suspended. |
feature_not_enabled | Feature isn’t enabled on this tenant. |
404 not_found
code | Meaning |
|---|
resource_not_found | No object with that ID visible to this tenant. |
409 conflict
code | Meaning |
|---|
duplicate_email | User with this email already exists. |
kyc_already_completed | KYC is finalized. |
transaction_not_pending | Transaction is past the point of this action. |
invite_already_accepted | Invite token has been consumed. |
429 rate_limit_error
code | Meaning |
|---|
rate_limit_exceeded | Honor Retry-After. |
5xx api_error
code | Meaning |
|---|
internal_error | Unexpected Zquence-side error. Retry with backoff. |
upstream_error | A dependent service is degraded. Retry with backoff. |
service_unavailable | Brief outage. Retry with backoff. |
Account endpoint codes
Create an account and
Retrieve an account return these codes in the top-level
code field of the response body, next to statusCode, message, path, correlationId,
and timestamp.
| Status | code | Meaning |
|---|
400 | invalid_idempotency_key | Idempotency-Key missing, not 8–255 characters, or contains spaces or non-ASCII characters. |
400 | unknown_request_fields | Body contains unsupported fields, listed in fields. |
400 | invalid_participants | participants isn’t one customer or one buyer plus one seller. |
400 | invalid_account_id | Account ID in the path isn’t valid. |
400 | invalid_external_read_context | API key isn’t bound to an environment (retrieve). |
401 | api_key_required | Endpoint accepts API-key authentication only. |
403 | environment_binding_required | API key isn’t bound to an environment (create). |
404 | account_not_found | No account with that ID in the key’s tenant and environment. |
409 | idempotency_key_reused | Idempotency-Key already used with a different body. |
409 | external_reference_exists | Another account already has this externalReference. |
When filing a support ticket, include the x-request-id header value from the failing response - it uniquely identifies the request across all our logs.
