Docs · errors
Error handling for production integrations.
Handle authentication, validation, credits, rate limits, and provider failures explicitly. Retry transient failures with exponential backoff; do not retry malformed requests or completed 200 responses.
Standard error body
VeracityAPI uses application/problem+json. Log instance and the x-request-id response header for support/debugging.
{
"type": "https://veracityapi.com/problems/rate_limited",
"title": "Too Many Requests",
"status": 429,
"detail": "Public demo limit reached. Try again later or create an account for API access.",
"instance": "req_01HX...",
"code": "rate_limited"
}Status codes
| Status | Cause | Client behavior |
|---|---|---|
400 | validation errors: malformed JSON, missing content, unsupported context, unsupported async mode, text shorter than 20 chars, or invalid URL. | Fix payload; do not retry unchanged. |
401 | Invalid or missing bearer API key. | Prompt for a fresh key; do not retry blindly. |
402 | insufficient credits / insufficient prepaid credits. | Show balance/top-up flow or reduce the run. |
413 | Content too large. | Chunk text or shrink media before retrying. |
415 | Unsupported media type. | Submit supported HTTPS or base64 image/audio input. |
429 | Rate limited. | Respect Retry-After; add an API key or slow the job. |
503 | Scoring model, provider, or video extractor unavailable. | Retry with exponential backoff, max 3 attempts. |
500 | Unexpected internal error. | Retry with backoff; contact support if persistent. |
Timeout guidance
- Text: 30s client timeout.
- Image/audio: 60s client timeout.
- Video private beta: 45s client timeout; direct HTTPS input capped at 30s/25MB.
- Batch: sync only; split large queues into batches of 25 or fewer text items.
Retry and billing guidance
- Retry only 429/5xx/503 responses, with jittered exponential backoff and a max of 3 attempts.
Idempotency-Keyis not implemented yet, so do not retry after a completed 200.- Provider failures after a debit are refunded by the API when caught as model/provider errors.
- Use
GET /v1/balancebefore large jobs.
Node try/catch skeleton
const res = await fetch("https://api.veracityapi.com/v1/analyze", {
method: "POST",
headers: {
"Authorization": "Bearer " + process.env.VERACITY_API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({ type: "text", content, context: { format: "article", intended_use: "publish" } })
});
if (!res.ok) {
const problem = await res.json();
if (res.status === 429 || res.status >= 500) retryLater(problem);
else throw new Error(problem.code + ": " + problem.detail);
}
const result = await res.json();