Error Handling

Vault returns errors as JSON with success: false and a message field. Use the HTTP status code and message to decide whether to retry, fix the request, or prompt the user.

Response format

{
  "success": false,
  "message": "Human-readable error message",
  "data": null
}

What to do by status

Code	Meaning	What to do
400	Bad Request	Fix input (see message); don’t retry same body
401	Unauthorized	Check API key or JWT; re-auth if token expired
403	Forbidden	Check permissions or MFA
404	Not Found	Token or resource doesn’t exist or was deleted
409	Conflict	Resolve duplicate or state conflict
429	Too Many Requests	Back off; use `retry_after_seconds` if present
5xx	Server/upstream error	Retry with exponential backoff

Handling in code

Check response.ok or response.status, then parse the JSON and use data.success and data.message. For 5xx and 429, retry after a delay. For 4xx (except 429), fix the request or show the message to the user.

Full reference

HTTP status codes — All status codes and typical causes.
Common errors — Frequent messages and how to fix them.

Getting Started

Vault

Payments

Error Handling

Error Handling

Response format

What to do by status

Handling in code

Full reference

​Error Handling

​Response format

​What to do by status

​Handling in code

​Full reference

Error Handling

Response format

What to do by status

Handling in code

Full reference