Fileverity API docs
Errors
The Fileverity API error format, HTTP statuses and the complete table of error codes, with guidance on which errors to retry.
View as MarkdownUpdated 2026-11-04
Errors use a standard HTTP status and a JSON body with a stable code. Branch on code, not on message: messages can change.
{ "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Unrecognized parameter: files.", "param": "files", "request_id": "req_4mQ9cX2vB7nP1sK8tL3wR6yZ" }}| Field | Description |
|---|---|
error.type | The category. One type maps to one HTTP status family, listed below. |
error.code | A stable, machine-readable identifier. |
error.message | A human-readable explanation. It can name the field or limit involved. |
error.param | The request field that caused the error, or null. |
error.request_id | The ID of this request, also in the x-request-id response header. Quote it when you contact support at hello@fileverity.com. |
Error types
| Type | Status | Meaning |
|---|---|---|
invalid_request_error | 400, 413, 415, 422 | The request is malformed or breaks a limit. Fix the request; retrying it unchanged fails again. |
authentication_error | 401 | The API key is missing or invalid. |
billing_error | 402 | The balance or a spend limit stops the request. Add funds or raise the limit. |
not_found_error | 404 | The resource does not exist, has expired or belongs to another workspace. |
conflict_error | 409 | The request conflicts with current state. |
rate_limit_error | 429 | Too many requests or too many pending uploads. For rate_limited, wait for retry-after seconds. pending_files_limit carries no retry-after: use, delete or wait for files to expire. |
api_error | 500, 502, 503 | A problem on our side or busy capacity. These requests were not charged. Retry with backoff. service_unavailable carries a retry-after header. |
What to retry
- Retry
rate_limitedafter theretry-afterseconds, andinternal_error,analysis_failedandservice_unavailablewith exponential backoff (forservice_unavailable, start with theretry-afterseconds). Send the sameIdempotency-Keyso a retry cannot run twice. See Idempotency. - Retry after waiting
idempotency_in_progress. - Do not retry other
4xxerrors until you change the request or the account state. - A check that ends in an error is not charged.
Still stuck? Write to hello@fileverity.com or use the contact page, and include the request ID.
Error codes
This table is generated from the API's own error definitions.
| Code | Status | Type | Message |
|---|---|---|---|
invalid_json | 400 | invalid_request_error | The request body must be a JSON object. |
missing_parameter | 400 | invalid_request_error | A required parameter is missing. |
invalid_parameter | 400 | invalid_request_error | A parameter has an invalid value. |
text_too_short | 400 | invalid_request_error | The text is too short to evaluate. Send at least 100 words. |
text_too_long | 413 | invalid_request_error | The text exceeds 100,000 characters. Split it into several requests. |
unsupported_media_type | 415 | invalid_request_error | Send the request body as JSON with the header "Content-Type: application/json". |
unsupported_language | 400 | invalid_request_error | The text is not in a supported language. Supported languages are en, fr, de, es and zh. |
file_not_found | 400 | invalid_request_error | The uploaded file was not found or has expired. Upload it again. |
unsupported_file | 415 | invalid_request_error | The file format is not supported for this model. |
file_too_large | 413 | invalid_request_error | The file exceeds the size limit for this model. |
too_many_pixels | 413 | invalid_request_error | The image exceeds 40 megapixels. |
too_many_pages | 413 | invalid_request_error | The document exceeds 100 pages. |
document_too_long | 413 | invalid_request_error | The document contains too much text to analyze in one request. |
invalid_file | 422 | invalid_request_error | The file is damaged or cannot be read. |
password_required | 422 | invalid_request_error | The document is encrypted. Send its password to analyze it. |
wrong_password | 422 | invalid_request_error | The document password is incorrect. |
not_examinable | 422 | invalid_request_error | The document has no text, photos or structure that can be examined. You were not charged. |
missing_api_key | 401 | authentication_error | No API key provided. Send it in the header "Authorization: Bearer fv_live_...". |
invalid_api_key | 401 | authentication_error | The API key is invalid or has been revoked. |
insufficient_balance | 402 | billing_error | Your balance is too low for this request. Top up your balance in the console. |
spend_limit_reached | 402 | billing_error | This API key has reached its monthly spend limit. Raise the limit in the console or wait until the next month (UTC). |
not_found | 404 | not_found_error | The requested resource does not exist. |
model_not_found | 404 | not_found_error | The model does not exist or is not available. |
not_cancelable | 409 | conflict_error | The analysis can no longer be canceled. |
canceled | 409 | conflict_error | The analysis was canceled. You were not charged. |
idempotency_mismatch | 409 | conflict_error | This Idempotency-Key was already used with a different request body. |
idempotency_in_progress | 409 | conflict_error | A request with this Idempotency-Key is still being processed. Retry shortly. |
pending_files_limit | 429 | rate_limit_error | This workspace has too many pending uploads. Analyze or delete uploaded files, or wait up to 24 hours for them to expire. |
rate_limited | 429 | rate_limit_error | Too many requests. Retry after the number of seconds in the Retry-After header. |
internal_error | 500 | api_error | The request could not be completed. Retry it; if the problem persists, contact support with the request ID. |
analysis_failed | 502 | api_error | The analysis could not be completed. You were not charged; retry it, and contact support with the request ID if it fails again. |
service_unavailable | 503 | api_error | The service is temporarily unavailable or busy. You were not charged; retry after the number of seconds in the Retry-After header. |
Console-only codes
These codes are returned by the Console's own endpoints, which work on your sign-in session. Requests made with an API key do not return them.
| Code | Status | Type | Message |
|---|---|---|---|
session_required | 401 | authentication_error | Sign in to continue. |
forbidden | 403 | permission_error | You do not have permission to do this. |
invite_invalid | 404 | not_found_error | This invitation is invalid, expired or already used. |
invite_mismatch | 403 | permission_error | This invitation was sent to a different email address. |
invite_limit | 409 | conflict_error | This workspace already has the maximum number of pending invitations. Revoke one first. |
last_owner | 409 | conflict_error | A workspace must keep at least one owner. Make another member an owner first. |
webhook_limit | 409 | conflict_error | This workspace already has the maximum number of webhook endpoints. Delete one first. |
key_limit | 409 | conflict_error | This workspace already has the maximum number of active API keys. Revoke one first. |