Valara

The standard error envelope returned by every /api/v1 endpoint, and what each type means.

Every /api/v1 error returns the same JSON envelope, so a client can handle all failures with one code path:

{
  "error": {
    "type": "insufficient_credits",
    "message": "Your credit balance is too low to start this review.",
    "param": null,
    "request_id": "req_8f3a…"
  }
}

Field	Description
`type`	A stable, machine-readable error category (see below). Branch on this, not on the message.
`message`	A human-readable explanation. May change; not for programmatic use.
`param`	The offending input field, when the error is about one.
`request_id`	Correlates the response with Valara server logs. Include it when you contact support.

Error types

Type	HTTP	Meaning
`invalid_request`	`400`	The request was malformed or failed validation. Check `param`.
`unauthorized`	`401`	Missing or invalid credentials. See Authentication.
`forbidden`	`403`	The key is valid but lacks the required scope, or the account is still pending admin approval.
`insufficient_credits`	`402`	Your credit balance is too low to start the review.
`not_found`	`404`	No such review, or the result is not ready yet.
`rate_limited`	`429`	Reserved. Rate limiting is not enforced yet, so no endpoint returns this today.
`server_error`	`500`	An unexpected error on Valara's side. Safe to retry with backoff.

Handling guidance

Branch on type, never on message or the raw status code alone.
402 insufficient_credits is the financial ceiling. Credits are checked before any work runs, so you are never charged for a rejected submit.
404 on a result usually means the review is still processing. Poll GET /api/v1/reviews/{id} until it is completed, then fetch the result.
429 rate_limited is reserved for when rate limiting is enabled; it is not enforced today. Handle it defensively anyway (back off and retry, honoring Retry-After) so your client is ready when it ships.
Always log request_id. It is the fastest way for support to find your request.

Errors

Error types

Handling guidance

On this page