Errors

Every error is a problem-details object (RFC 9457) with a stable code you can branch on, a sentence you can show people, and a request id for support.

The error shape

An error

HTTP/1.1 402 Payment Required
Content-Type: application/problem+json
Request-Id: req_0vZ3pQ8rS1tU2vW3xY4zA5

{
  "type": "https://vindexgrid.com/docs/api/errors/#insufficient_credits",
  "title": "Not enough credits",
  "status": 402,
  "detail": "Creating this verification needs 70 credits; your live balance has 12. …",
  "code": "insufficient_credits",
  "doc_url": "https://vindexgrid.com/docs/api/errors/#insufficient_credits",
  "request_id": "req_0vZ3pQ8rS1tU2vW3xY4zA5",
  "required": 70,
  "available": 12
}

code is stable: branch on it. title and detail are for people and may be reworded.
type and doc_url link to the code's entry on this page.
request_id (also the Request-Id header) finds the request in your log; quote it to support.
Some codes add fields: required and available on 402, required_scope on 403.
The content type is application/problem+json; a normal JSON parser reads it.

Which errors to retry

Retry 429, 409 idempotency_key_in_use, 500 and 503, with backoff and the same Idempotency-Key. Don't retry other 4xx errors unchanged: fix the request first.

Validation errors

When fields are wrong, errors[] lists each one with a dotted param, a JSON Pointer (RFC 6901) to the field, and what is wrong. param at the top level is the first of them.

422

{
  "type": "https://vindexgrid.com/docs/api/errors/#validation_failed",
  "title": "Some fields are not valid",
  "status": 422,
  "detail": "One or more fields failed validation; see errors[].",
  "code": "validation_failed",
  "param": "individual.last_name",
  "errors": [
    {
      "param": "individual.last_name",
      "pointer": "#/individual/last_name",
      "detail": "Field required",
      "code": "missing"
    }
  ],
  "request_id": "req_0vZ3qR9sT2uV3wX4yZ5aB6"
}

Error codes

400Bad request

invalid_requestThe request is not valid

The body or a query parameter can't be understood.

What to do: Check the request against the reference: a body that isn't JSON, or a parameter of the wrong kind.

401Not authenticated

authentication_requiredAuthentication required

No API key was sent. Send Authorization: Bearer <key>.

What to do: Send your key: Authorization: Bearer vdx_test_… or vdx_live_….

invalid_api_keyInvalid API key

The key is malformed, unknown, or belongs to another environment.

What to do: Check you copied the whole key, and that it is a test key for test mode and a live key for live mode.

api_key_revokedAPI key revoked

The key was revoked. Create or roll a key in the Developers console.

What to do: Use another key, or create one in the Developers console.

api_key_expiredAPI key expired

The key passed its expiry date.

What to do: Roll the key, or create a new one, in the Developers console.

402Payment required

insufficient_creditsNot enough credits

The balance can't cover this operation. Buy credits or enable auto-recharge.

What to do: Buy credits (or turn on auto-recharge), then retry. required and available say how many you need.

403Forbidden

ip_not_allowedAddress not allowed

The key has an IP allowlist and this address is not on it.

What to do: Call from an address on the key's allowlist, or add this address to it.

secret_key_in_browserSecret key used from a browser

API keys are secret and must only be used from your server, never from web pages or apps.

What to do: Move the call to your server. Keys must never be in web pages or apps.

insufficient_scopeKey not permitted

The key's permissions don't include this operation.

What to do: Use a key with the permission in required_scope, or widen this key's permissions.

live_mode_not_enabledLive mode not enabled

Your account can use test keys until Vindex approves live access.

What to do: Keep building with your test key; apply for live access in the console.

account_suspendedAccount suspended

API access is suspended for this account. Contact Vindex.

What to do: Contact Vindex.

feature_not_enabledNot available yet

This operation is not enabled for your account.

What to do: The detail says what isn't available yet. It works in test mode.

usage_limit_reachedMonthly usage limit reached

Your own monthly usage limit stops further paid calls.

What to do: An owner or admin can raise your monthly usage limit in the console.

404Not found

not_foundNot found

No such object exists in this environment.

What to do: Check the id, and that you are using a key of the same mode the object was created in.

409Conflict

report_not_readyReport not ready

This report exists only after a decision, or is still being generated.

What to do: Wait for the report.ready webhook, then download.

invalid_stateNot possible now

The object is in a state that doesn't allow this.

What to do: Read the object: the detail says why this isn't possible in its current status.

idempotency_key_in_useRequest already in progress

Another request with this Idempotency-Key is still running.

What to do: Wait a second (Retry-After) and retry with the same key.

422Unprocessable

validation_failedSome fields are not valid

One or more fields failed validation; see errors[].

What to do: Fix the fields listed in errors[]; each has a pointer to the field and what is wrong.

idempotency_key_reusedIdempotency-Key reused

This Idempotency-Key was used with different parameters.

What to do: Use a new Idempotency-Key for a new request.

429Too many requests

rate_limitedToo many requests

Slow down; retry after the number of seconds in Retry-After.

What to do: Wait the number of seconds in Retry-After, then retry. Spread bursts out.

500Server error

internal_errorSomething went wrong

An unexpected error. Retry with the same Idempotency-Key.

What to do: Retry with the same Idempotency-Key. If it keeps happening, send Vindex the request_id.

503Service unavailable

provider_unavailableService temporarily unavailable

A screening provider is unavailable; nothing was charged.

What to do: Nothing was charged. Retry later with the same Idempotency-Key.

Keys, limits and conventionsAPI keys, test and live mode, versions, request ids, rate limits, safe retries, paging and metadata.API referenceEvery endpoint, field, error and webhook event, with code in curl, Node and Python.

Something missing or unclear? Signed-in users can tell us from Feedback in the app.