# Errors and retries

Handle Lingopal API authentication errors, validation failures, partial batch results, and safe retries.

URL: /guides/errors-and-validation



Check the response status before reading the body. Error details can vary by operation, so use the response schema in the [API Reference](/reference) as the source of truth.

| Status | Meaning                                             | Action                                                                          |
| ------ | --------------------------------------------------- | ------------------------------------------------------------------------------- |
| `401`  | Missing or invalid API key                          | Check the `X-API-Key` header and key status                                     |
| `403`  | The authenticated caller cannot access the resource | Confirm the resource belongs to the current account and that the key has access |
| `404`  | The requested job, upload, or output was not found  | Verify identifiers and confirm the workflow produced the requested output       |
| `413`  | The direct upload exceeds the accepted size         | Use a storage upload instead                                                    |
| `422`  | The request failed validation                       | Inspect the returned error body and correct the request                         |
| `5xx`  | A server-side failure occurred                      | Retry transient failures with backoff; contact support if the failure persists  |

## Validation errors [#validation-errors]

Validation responses commonly identify the invalid field and explain the failure, but the exact body depends on the operation. Do not assume every `422` response has the same `detail[]` shape; check the operation's documented response.

## Batch registration [#batch-registration]

`POST /v2/jobs/register` can return HTTP `200` while individual items fail. Check `results[].status`, `registered_count`, and `error_count`; retain each successful `job_id` independently.

## Retry safely [#retry-safely]

Retry transient server or network failures with exponential backoff and jitter. Do not automatically retry authentication, authorization, not-found, or validation errors without correcting their cause. For asynchronous processing failures, inspect the [job lifecycle](/guides/jobs/job-lifecycle) before starting another workflow.