# Errors

> The Fileverity API error format, HTTP statuses and the complete table of error codes, with guidance on which errors to retry.

Source: https://fileverity.com/en/docs/errors

Errors use a standard HTTP status and a JSON body with a stable `code`. Branch on `code`, not on `message`: messages can change.

**Error response**

```json
{
  "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](mailto: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_limited` after the `retry-after` seconds, and `internal_error`, `analysis_failed` and `service_unavailable` with exponential backoff (for `service_unavailable`, start with the `retry-after` seconds). Send the same `Idempotency-Key` so a retry cannot run twice. See [Idempotency](https://fileverity.com/en/docs/idempotency.md).
- **Retry after waiting** `idempotency_in_progress`.
- **Do not retry** other `4xx` errors 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](mailto:hello@fileverity.com) or use the [contact page](https://fileverity.com/en/contact), 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. |