Error Codes
A comprehensive reference of every error code the Vantax API can return, the HTTP status it maps to, and what it means.
When a request fails, the API responds with a standard HTTP status code and a JSON body following the error envelope — { "success": false, "message": "..." }. Each failure mode maps to one of the stable error codes below. Match on the HTTP status for coarse handling, and use the codes here to drive specific recovery logic.
Handle codes, not strings
The
message field is human-readable and may change over time. Branch on the HTTP status (and, for validation errors, the per-field errors array) rather than parsing the message text.Reference
| Code | HTTP status | Meaning |
|---|---|---|
unauthorized | 401 | No credentials were supplied, or the Authorization / x-api-key header was missing or malformed. |
invalid_api_key | 401 | The API key was provided but is revoked, expired, or does not exist. |
forbidden_scope | 403 | The key's scope cannot reach this endpoint — e.g. an agency key calling a sub-account resource, or vice-versa. |
not_found | 404 | The requested resource does not exist, or is not visible to the account derived from your key. |
conflict | 409 | The request conflicts with the current state of the resource, such as a duplicate or a version mismatch. |
validation_failed | 422 | One or more fields failed validation. See the errors array for per-field details. |
rate_limited | 429 | Too many requests in a given window. Back off and retry after the interval indicated by the response headers. |
subscription_required | 402 | The account has no active subscription that covers this endpoint or feature. |
limit_reached | 402 | A plan quota or usage limit has been exhausted for the current billing period. |
internal_error | 500 | An unexpected error occurred on our side. The request can usually be retried safely. |