Errors and retries
Handle Lingopal API authentication errors, validation failures, partial batch results, and safe retries.
Check the response status before reading the body. Error details can vary by operation, so use the response schema in the API 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 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
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 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 before starting another workflow.