> This page is for version v1 (default). > For other versions, use one of these documentation indexes: > - v1 (default): https://docs.plextera.com/v-1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.plextera.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.plextera.com/_mcp/server. # Errors Application error responses from the Plextera Public API use one envelope, so you can share one error handler across endpoints. Network-edge responses such as rate limiting can contain plain text instead; always check the HTTP status and response content type before parsing JSON. ```json { "error": { "code": "VALIDATION_FAILED", "message": "Endpoint URL must use https.", "requestId": "req_E906121DE9DA4367AF978C77C9", "retryable": false, "details": [ { "field": "endpointUrl", "issue": "Endpoint URL must use https." } ] } } ``` | Field | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | Stable machine-readable error code. Branch your handling on this, not on `message`. | | `message` | Human-readable explanation. Safe to log and show to operators; wording may change. | | `requestId` | Unique request identifier, also returned in the `X-Request-Id` response header. Include it in support requests. | | `retryable` | `true` when retrying the same request later may succeed. | | `details` | Field-level validation issues. Present only for `VALIDATION_FAILED`. `details[].field` is the JSON path of the rejected field, exactly as you sent it (`name`, `endpointUrl`, `eventTypes[1]`, `document.url`) - match on it. `details[].issue` is the reason, written for a person (`Endpoint URL must use https.`) - display it. | > **Tip** > > You can send your own `X-Request-Id` header with any request. Plextera echoes it back in the response and in error payloads, which makes cross-system log correlation trivial. ## Error codes The `message` field is human-readable and operation-specific: real messages name the exact resource and identifier (for example `Document Insights extraction not found: 69654f0bc073ef404baec649`), and their wording may change without notice. For `VALIDATION_FAILED`, `message` names the fields that were rejected and why - it is a readable rendering of `details`, not a separate summary, so a form can show it as-is when it has nowhere better to put the text. Requests failing on many fields render the first few and count the rest; `details` always lists all of them. The per-endpoint examples in the [API Reference](/api/api-reference) show typical real messages for each operation. Branch programmatic handling on `code` and, for validation errors, on `details[].field` - never on `message`. | HTTP status | Code | Meaning | What to do | | ----------- | ------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | 400 | `INVALID_REQUEST` | The request is malformed: unreadable JSON, an invalid parameter value, or a bad multipart body. | Fix the request before retrying. | | 401 | `UNAUTHORIZED` | The API key is missing, malformed, or revoked. | Check the `Authorization: api-key ` header. See [Authentication](/guides/introduction/authentication). | | 403 | `FORBIDDEN` | The API key is valid but not allowed to perform this operation. | Contact your workspace administrator. | | 404 | `NOT_FOUND` | The resource does not exist in your workspace, or the path is wrong. | Verify the identifier and the URL. | | 405 | `METHOD_NOT_ALLOWED` | The HTTP method is not supported for this path. | Check the API reference for the supported methods. | | 406 | `NOT_ACCEPTABLE` | The requested response media type is not supported. | Use `Accept: application/json`. | | 409 | `CONFLICT` | The request conflicts with the current resource state. | Inspect `retryable`; re-read the resource and retry if `true`. | | 413 | `PAYLOAD_TOO_LARGE` | The uploaded file exceeds the maximum supported size (50 MB). | Reduce the file size. | | 415 | `UNSUPPORTED_MEDIA_TYPE` | The request content type is unsupported, or the uploaded file type is blocked (executables and scripts). | Send the expected content type or a supported file type. | | 422 | `VALIDATION_FAILED` | The request shape is valid but one or more field values are not. | Fix the fields listed in `details`. | | 429 | `RATE_LIMITED` | You have sent too many requests in a short window. | Back off and retry after the `Retry-After` header. | | 500 | `INTERNAL_ERROR` | Unexpected failure inside Plextera. | Retry with backoff. If it persists, contact support with the `requestId`. | | 502 | `DOWNSTREAM_ERROR` | A downstream Plextera service failed while handling the request. | Retry with backoff. If it persists, contact support with the `requestId`. | ## Retry guidance * Retry only when `retryable` is `true` or the HTTP status is `5xx`. * On `429`, wait for the `Retry-After` header (seconds) before retrying. Rate limits are enforced at the network edge, so a `429` body may be plain text instead of the JSON envelope - rely on the status code and the `Retry-After` header. Prefer event subscriptions over tight polling to stay within rate limits. * Use exponential backoff with jitter; start around 1 second and cap at 30-60 seconds. * Creation endpoints are not idempotent: if a `POST /document-insights/extractions` request times out client-side, list recent extractions (filtered by your `labels`) before blindly retrying, or you may create a duplicate extraction. ## API errors vs. processing failures The error envelope above describes **request** failures: the API rejected or could not handle the HTTP call. A successfully accepted document can still **fail processing** later. That outcome is not an HTTP error: the extraction or workflow run is returned with status `FAILED` or `REJECTED` and a `RunError` object (`error.code`, `error.message`) inside the resource payload. See [Document Extraction - Handle failures](/guides/core-guides/document-extraction#handle-failures). ## Related reference * [API Reference](/api/api-reference) - per-endpoint error responses * [Event Subscriptions](/guides/core-guides/event-subscriptions) - webhook delivery retry behavior