Operations

Errors, limits, and retries

Handle failures predictably without retrying invalid requests.

On this page

HTTP statuses

Status	Meaning	Retry?
400	Invalid JSON, model, parameters, or context.	No; fix the request.
401	Missing or invalid API key.	No; fix authentication.
402	Insufficient prepaid balance.	No; add funds.
403	Feature or access not allowed.	Not without changing plan/request.
404	Model not found for the key.	No; query /models.
413	Payload exceeds the limit.	No; reduce the request.
428	Terms acceptance required.	After accepting the terms.
429	Rate limit reached.	Yes; honor Retry-After.
500	Unexpected internal failure.	Yes, with a retry cap.
502	Invalid provider response.	Yes, with backoff.
503	Capacity, billing, or dependency unavailable.	Yes, with backoff.

Header	Description
X-RateLimit-Limit	Configured allowance for the current window.
X-RateLimit-Remaining	Remaining allowance.
X-RateLimit-Reset	Unix reset timestamp.
Retry-After	Minimum delay before retrying after a 429.

Common error

{
  "error": "invalid API key"
}

Structured output not enabled

{
  "error": "structured output is not enabled for this plan",
  "code": "structured_output_not_enabled"
}

Terms acceptance

{
  "error": "terms_acceptance_required",
  "version": "2026-08",
  "acceptUrl": "https://code.verboo.ai/pt/terms/accept"
}

Retry only 429, 500, 502, and 503, plus idempotent network failures before a response starts.
Use Retry-After when present; otherwise apply exponential backoff with jitter.
Set a maximum attempt count and total timeout.
Do not automatically retry after a stream has already delivered content.