Sandbox docs

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 — 409 idempotency_key_reuse.
  • rate_limit_error — 429.
  • api_error — 5xx temporary platform failure.

HTTP mapping

StatusWhen
400Invalid JSON or field validation.
401Missing or invalid Bearer credential.
403Authenticated but missing scope or forbidden for this account.
404Unknown resource id.
409Conflict, including idempotency_key_reuse.
429Rate limited. Honour Retry-After / reset headers.
5xxTemporary platform failure. Retry with the same idempotency key.

Common codes

  • validation_error, unauthorized, forbidden, missing_scope
  • resource_not_found, idempotency_key_reuse, rate_limited
  • quote_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.