Introduction

Errors

One error envelope across every endpoint

Every error response from the Plextera Public API uses one envelope, so you can write a single error handler for all endpoints.

1{
2  "error": {
3    "code": "VALIDATION_FAILED",
4    "message": "One or more request fields are invalid.",
5    "requestId": "req_E906121DE9DA4367AF978C77C9",
6    "retryable": false,
7    "details": [
8      { "field": "endpointUrl", "issue": "must not be blank" }
9    ]
10  }
11}
FieldDescription
codeStable machine-readable error code. Branch your handling on this, not on message.
messageHuman-readable explanation. Safe to log and show to operators; wording may change.
requestIdUnique request identifier, also returned in the X-Request-Id response header. Include it in support requests.
retryabletrue when retrying the same request later may succeed.
detailsField-level validation issues. Present only for VALIDATION_FAILED.

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. The per-endpoint examples in the 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 statusCodeMeaningWhat to do
400INVALID_REQUESTThe request is malformed: unreadable JSON, an invalid parameter value, or a bad multipart body.Fix the request before retrying.
401UNAUTHORIZEDThe API key is missing, malformed, or revoked.Check the Authorization: api-key <token> header. See Authentication.
403FORBIDDENThe API key is valid but not allowed to perform this operation.Contact your workspace administrator.
404NOT_FOUNDThe resource does not exist in your workspace, or the path is wrong.Verify the identifier and the URL.
405METHOD_NOT_ALLOWEDThe HTTP method is not supported for this path.Check the API reference for the supported methods.
406NOT_ACCEPTABLEThe requested response media type is not supported.Use Accept: application/json.
409CONFLICTThe request conflicts with the current resource state.Inspect retryable; re-read the resource and retry if true.
413PAYLOAD_TOO_LARGEThe uploaded file exceeds the maximum supported size (50 MB).Reduce the file size.
415UNSUPPORTED_MEDIA_TYPEThe 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.
422VALIDATION_FAILEDThe request shape is valid but one or more field values are not.Fix the fields listed in details.
429RATE_LIMITEDYou have sent too many requests in a short window.Back off and retry after the Retry-After header.
500INTERNAL_ERRORUnexpected failure inside Plextera.Retry with backoff. If it persists, contact support with the requestId.
502DOWNSTREAM_ERRORA 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 tags) 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.