{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-index.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Error Codes","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"style":{"color":"#cdcefb","fontSize":"14px","fontWeight":"700","textTransform":"uppercase","letterSpacing":"0.05em","display":"block","marginBottom":"-30px"}},"children":["Get Started"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"error-codes","__idx":0},"children":["Error Codes"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Understanding and handling Anesya API errors."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When something goes wrong, the Anesya API returns an HTTP status code and a JSON error payload."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The public schema currently documents a compact error model based mainly on:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["authentication errors"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["validation errors"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["not found errors"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["resource-specific runtime failure states exposed inside parsing and extract resources"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-response-format","__idx":1},"children":["Error response format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The public API schema documents these main error shapes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authentication-error","__idx":2},"children":["Authentication error"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"detail\": \"Invalid API key\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"not-found-error","__idx":3},"children":["Not found error"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"detail\": \"Parsing not found.\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"validation-error","__idx":4},"children":["Validation error"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Validation errors may use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]},", field names, or both."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"detail\": \"Missing or invalid fields\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Or:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"document\": [\n    \"This field is required.\"\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The schema describes validation errors as:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a string"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["or an array of strings"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["keyed by field name or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"documented-http-status-codes","__idx":5},"children":["Documented HTTP status codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These are the status codes explicitly documented in the public schema."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Where it appears"},"children":["Where it appears"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Typical handling"},"children":["Typical handling"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource retrieved successfully"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["list and retrieve endpoints"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["consume response normally"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource created and processing started"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["create endpoints"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["store returned ID and continue"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["302"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Redirect to file download URL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["document download"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["follow redirect"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or invalid request fields"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["create endpoints"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["inspect validation payload and fix request"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or invalid API key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["most protected endpoints"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["fix authentication"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource not found"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["retrieve and download endpoints"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["verify the resource ID"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The public schema does ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," currently document a broader catalog such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}," error payload shapes, so this page does not invent them."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"by-endpoint-family","__idx":6},"children":["By endpoint family"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"documents","__idx":7},"children":["Documents"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Possible documented errors"},"children":["Possible documented errors"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v0/documents"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v0/documents"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v0/documents/{id}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v0/documents/{id}/download"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["302"]}," redirect on success"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"parsings","__idx":8},"children":["Parsings"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Possible documented errors"},"children":["Possible documented errors"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v0/parsing"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v0/parsing"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v0/parsing/{id}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"extracts","__idx":9},"children":["Extracts"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Possible documented errors"},"children":["Possible documented errors"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v0/extract"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v0/extract/{id}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"important-distinction-http-errors-vs-resource-failures","__idx":10},"children":["Important distinction: HTTP errors vs resource failures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some failures are returned as HTTP errors."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Other failures happen ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["inside"]}," asynchronous resources after creation succeeds."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is especially important for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["parsing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["extract"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request may return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]},", but the created resource can later end with:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["parsing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: ERROR"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["extract ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: ERROR"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["So for asynchronous resources, success of the initial HTTP request does ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," mean success of the processing job."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-parsing-failures","__idx":11},"children":["Handling parsing failures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Parsing has two kinds of failure signals:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-request-time-validation-errors","__idx":12},"children":["1. Request-time validation errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common causes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["malformed JSON body"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["unsupported payload shape"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-resource-time-processing-errors","__idx":13},"children":["2. Resource-time processing errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These appear after the parsing resource has already been created."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You must inspect:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Possible terminal statuses:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FINISHED"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARTIAL_FINISHED"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ERROR"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example failure-shaped parsing resource:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"PARSING_ID\",\n  \"status\": \"ERROR\",\n  \"error\": \"Unable to process the provided document.\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recommended handling:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v0/parsing"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", fix the request"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["if creation returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]},", poll ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v0/parsing/{id}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["if the final status is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ERROR"]},", inspect the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," field"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["if the final status is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARTIAL_FINISHED"]},", inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pages_failed"]}," before deciding whether to continue"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-extract-failures","__idx":14},"children":["Handling extract failures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Extract also has two failure layers."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-request-time-validation-errors-1","__idx":15},"children":["1. Request-time validation errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common causes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["sending both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parsing"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["malformed request body"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-resource-time-processing-errors-1","__idx":16},"children":["2. Resource-time processing errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These appear on the extract resource after a successful creation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You must inspect:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Possible terminal statuses:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FINISHED"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ERROR"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example failure-shaped extract resource:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"EXTRACT_ID\",\n  \"status\": \"ERROR\",\n  \"error\": \"Schema could not be applied to the current input.\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recommended handling:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v0/extract"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", fix the request"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["if creation returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]},", poll ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v0/extract/{id}"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["if the final status is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ERROR"]},", inspect the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," field"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["if output quality is wrong, inspect the upstream parsing before blaming the schema"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-issues","__idx":17},"children":["Common issues"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"400-missing-or-invalid-fields","__idx":18},"children":["400: Missing or invalid fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This usually means the request shape is wrong."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Typical causes by endpoint:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["documents: missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["parsing: missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["extract: missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["extract: both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parsing"]}," were sent"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Solution:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["inspect the validation payload"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["fix the request body or multipart form"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["retry with the corrected payload"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"401-missing-or-invalid-authentication","__idx":19},"children":["401: Missing or invalid authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This means the API key is missing or invalid."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Solution:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["ensure the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-API-Key"]}," header is present"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["ensure the key value is correct"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["ensure you are calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.anesya.app"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"404-resource-not-found","__idx":20},"children":["404: Resource not found"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This means the referenced resource ID is missing or unknown to the current workspace context."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Typical causes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["wrong document ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["wrong parsing ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["wrong extract ID"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Solution:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["verify the UUID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["verify that the resource was created successfully earlier"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["verify that your application is using the correct workspace credentials"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"302-download-redirect","__idx":21},"children":["302: Download redirect"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is not a failure."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is the documented success behavior for document download."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Solution:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["follow the redirect"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["or handle the redirected URL explicitly in your client"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-errors-in-code","__idx":22},"children":["Handling errors in code"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Even without a dedicated SDK-level error taxonomy documented here, a safe strategy is:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["check the HTTP status code"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["parse the JSON response body if present"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}," or field-level validation messages"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["for asynchronous resources, poll and inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"curl-pattern","__idx":23},"children":["cURL pattern"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"RESPONSE=$(curl -s -w \"\\n%{http_code}\" -X POST \"https://api.anesya.app/v0/extract\" \\\n  -H \"X-API-Key: $ANESYA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"parsing\": \"YOUR_PARSING_ID\",\n    \"schema\": \"YOUR_SCHEMA_ID\"\n  }')\n\nSTATUS=$(echo \"$RESPONSE\" | tail -n 1)\nBODY=$(echo \"$RESPONSE\" | sed '$d')\n\nif [ \"$STATUS\" -eq 201 ]; then\n  echo \"Created: $BODY\"\nelif [ \"$STATUS\" -eq 400 ]; then\n  echo \"Validation error: $BODY\"\nelif [ \"$STATUS\" -eq 401 ]; then\n  echo \"Authentication error: $BODY\"\nelif [ \"$STATUS\" -eq 404 ]; then\n  echo \"Not found: $BODY\"\nelse\n  echo \"Unexpected response $STATUS: $BODY\"\nfi\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"application-level-strategy","__idx":24},"children":["Application-level strategy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For create endpoints:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}," as “resource created”, not “processing finished”"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For retrieve endpoints:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," as “resource retrieved”"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," inside parsing or extract resources"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For download:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["302"]}," as success"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"recommended-retry-behavior","__idx":25},"children":["Recommended retry behavior"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The public documentation available here does not define an official retry matrix."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A conservative strategy is:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["do ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," blindly retry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["do ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," blindly retry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["do ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," blindly retry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["retry only after fixing the cause or when the input becomes valid"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For asynchronous resources:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["poll until a final state"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["if the final state is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ERROR"]},", inspect the resource-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["only retry after correcting the input, schema, or upstream workflow"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting-checklist","__idx":26},"children":["Troubleshooting checklist"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an Anesya request fails, check in this order:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Is the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-API-Key"]}," header present?"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Is the request body valid JSON or valid multipart form-data?"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Are required fields present?"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If using IDs, do the referenced resources exist?"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If creating a parsing or extract, did you poll the created resource to a final state?"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If extract failed, does the upstream parsing look correct?"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If document download failed, did your client follow the redirect?"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-guides","__idx":27},"children":["Related guides"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/quickstart"},"children":["API quickstart"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/documents"},"children":["Documents"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/parsing"},"children":["Parsing"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/extract"},"children":["Extract"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/quickstart"},"children":["Quickstart polling flow"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/agent-guide"},"children":["Anesya API Reference for Coding Agents"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/schema"},"children":["API reference"]}]}]}]},"headings":[{"value":"Error Codes","id":"error-codes","depth":1},{"value":"Error response format","id":"error-response-format","depth":2},{"value":"Authentication error","id":"authentication-error","depth":3},{"value":"Not found error","id":"not-found-error","depth":3},{"value":"Validation error","id":"validation-error","depth":3},{"value":"Documented HTTP status codes","id":"documented-http-status-codes","depth":2},{"value":"By endpoint family","id":"by-endpoint-family","depth":2},{"value":"Documents","id":"documents","depth":3},{"value":"Parsings","id":"parsings","depth":3},{"value":"Extracts","id":"extracts","depth":3},{"value":"Important distinction: HTTP errors vs resource failures","id":"important-distinction-http-errors-vs-resource-failures","depth":2},{"value":"Handling parsing failures","id":"handling-parsing-failures","depth":2},{"value":"1. Request-time validation errors","id":"1-request-time-validation-errors","depth":3},{"value":"2. Resource-time processing errors","id":"2-resource-time-processing-errors","depth":3},{"value":"Handling extract failures","id":"handling-extract-failures","depth":2},{"value":"1. Request-time validation errors","id":"1-request-time-validation-errors-1","depth":3},{"value":"2. Resource-time processing errors","id":"2-resource-time-processing-errors-1","depth":3},{"value":"Common issues","id":"common-issues","depth":2},{"value":"400: Missing or invalid fields","id":"400-missing-or-invalid-fields","depth":3},{"value":"401: Missing or invalid authentication","id":"401-missing-or-invalid-authentication","depth":3},{"value":"404: Resource not found","id":"404-resource-not-found","depth":3},{"value":"302: Download redirect","id":"302-download-redirect","depth":3},{"value":"Handling errors in code","id":"handling-errors-in-code","depth":2},{"value":"cURL pattern","id":"curl-pattern","depth":3},{"value":"Application-level strategy","id":"application-level-strategy","depth":3},{"value":"Recommended retry behavior","id":"recommended-retry-behavior","depth":2},{"value":"Troubleshooting checklist","id":"troubleshooting-checklist","depth":2},{"value":"Related guides","id":"related-guides","depth":2}],"frontmatter":{"seo":{"title":"Error Codes"}},"lastModified":"2026-04-22T15:07:29.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/tutorials/error-codes","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}