Errors
Failures use one envelope. Branch on error.code. Never parse message, and never expect SQL, processor, or provider codes in this document.
Envelope
JSON
{
"error": {
"type": "invalid_request_error",
"code": "validation_error",
"message": "Amount must be greater than zero.",
"param": "amount",
"request_id": "vreq_01EXAMPLE"
}
}Error types
error.type is the coarse family; error.code is the stable branch key. The six types are:
invalid_request_error— 400 validation, 404 unknown id, 409 state conflicts other than idempotency.authentication_error— 401 missing or invalid credential.authorization_error— 403 missing scope or forbidden account.idempotency_error— 409idempotency_key_reuse.rate_limit_error— 429.api_error— 5xx temporary platform failure.
HTTP mapping
| Status | When |
|---|---|
| 400 | Invalid JSON or field validation. |
| 401 | Missing or invalid Bearer credential. |
| 403 | Authenticated but missing scope or forbidden for this account. |
| 404 | Unknown resource id. |
| 409 | Conflict, including idempotency_key_reuse. |
| 429 | Rate limited. Honour Retry-After / reset headers. |
| 5xx | Temporary platform failure. Retry with the same idempotency key. |
Common codes
validation_error,unauthorized,forbidden,missing_scoperesource_not_found,idempotency_key_reuse,rate_limitedquote_expired,unsupported_currency,payment_failed,ledger_funds_unavailable(409 — the merchant ledger no longer holds the funds for a refund; in the sandbox this happens for payments created before the last sandbox reset),internal_error
Request IDs
Every response includes a Vestonix request id (vreq_) in the JSON envelope and as X-Vestonix-Request-Id / X-Request-Id. Quote that id when you contact support. Do not send processor references — they are not part of the public contract.