Errors

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.

Introduction

Tenant

Environments

Customers

Accounts

KYC

Document reviews

Source of funds

Files

Webhooks

Sync

Sanctions

Error envelope

By status code

`400` validation_error

`401` authentication_error

`403` permission_error

`404` not_found

`409` conflict

`429` rate_limit_error

`5xx` api_error

Account endpoint codes

​Error envelope

​By status code

​400 validation_error

​401 authentication_error

​403 permission_error

​404 not_found

​409 conflict

​429 rate_limit_error

​5xx api_error

​Account endpoint codes

Error envelope

By status code

`400` validation_error

`401` authentication_error

`403` permission_error

`404` not_found

`409` conflict

`429` rate_limit_error

`5xx` api_error

Account endpoint codes