Error Handling

Every Vouchley API error returns a consistent JSON body with an HTTP status code you can branch on.

Error format

All error responses have the same shape — a JSON object with a detail field containing a human-readable message:

{
  "detail": "Insufficient credits. Purchase a credit pack to continue."
}

Code	Meaning	What to do
200	Success	Process the response normally.
202	Accepted (bulk only)	Job queued. Poll `GET /v1/jobs/:id` for results.
400	Bad request	Check your request body — missing or invalid fields.
401	Unauthorized	API key is missing, invalid, or revoked.
402	Payment required	Credit balance is zero. Purchase a plan.
404	Not found	The requested resource (check, job) doesn't exist.
422	Validation error	Request body failed schema validation (e.g. invalid email format).
429	Rate limited	Back off and retry. See Rate Limits.
500	Server error	Retry with backoff. If persistent, contact support.

Missing Authorization header — Every request must include Authorization: Bearer vch_.... Double-check your key is set in the environment.

Invalid API key — The key may have been revoked. Check the API Keys page in your dashboard.

Insufficient credits — Your balance is zero. Subscribe to a plan or wait for your next billing cycle if you already have an active subscription.