Skip to navigation
Introduction

Errors

One error envelope across every endpoint

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.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Endpoint URL must use https.",
    "requestId": "req_E906121DE9DA4367AF978C77C9",
    "retryable": false,
    "details": [
      { "field": "endpointUrl", "issue": "Endpoint URL must use https." }
    ]
  }
}
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. 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.

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 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 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.