Errors · Docs

Vaelor uses conventional HTTP status codes. Codes in the 2xx range mean success, 4xx means something about the request needs to change, and 5xx means something went wrong on our side or with an upstream model provider.

Error shape#

Every error response is JSON with a human-readable error message. Some errors add a stable, machine-readable code and extra fields.

JSON

{
  "error": "Not enough usage credits",
  "code": "INSUFFICIENT_USAGE_CREDITS",
  "required": 60,
  "remaining": 14,
  "nextRefreshAt": "2026-10-20T12:00:00.000Z"
}

Branch on status and code, never on the error text — messages are written for people and may change.

Status codes#

Status	Meaning
`200`	Success.
`201`	A resource was created.
`202`	Work was accepted and continues in the background.
`400`	The body failed validation, or a parameter is missing or out of range.
`401`	The API key is missing, malformed or deleted.
`402`	Not enough credits to start the request.
`403`	The key is valid but can't perform this action.
`404`	The resource doesn't exist or belongs to another account.
`409`	Conflicts with current state — a duplicate request ID, or an active run.
`413`	An uploaded file is too large.
`429`	Too many requests. Back off and retry.
`502`	The upstream model provider failed. Safe to retry.
`503`	The feature is temporarily unavailable. Retry later.

Error codes#

Code	Status	What to do
`INSUFFICIENT_USAGE_CREDITS`	402	Wait until `nextRefreshAt`, upgrade your plan, or buy credits.
`DUPLICATE_REQUEST`	409	A track already exists for this `requestId`. Fetch it instead.
`KEY_LIMIT_REACHED`	409	Delete an unused API key before creating another.
`rate_limited`	429	Too many verification attempts. Wait an hour.

Insufficient credits#

A 402 is returned before any work starts, so nothing is charged. The body tells you how many credits the request needs, how many you have, and when your plan credits refresh.

Retrying#

Retry 502 and 503 with exponential backoff — for example 1s, 2s, 4s, up to 5 attempts.
Don't retry 400, 401, 403 or 404 without changing the request.
Use idempotency keys when retrying music and OSINT requests, so a retry never creates a duplicate.