Skip to content
Last updated

Get Started

Error Codes

Understanding and handling Anesya API errors.

When something goes wrong, the Anesya API returns an HTTP status code and a JSON error payload.

The public schema currently documents a compact error model based mainly on:

  • authentication errors
  • validation errors
  • not found errors
  • resource-specific runtime failure states exposed inside parsing and extract resources

Error response format

The public API schema documents these main error shapes.

Authentication error

{
  "detail": "Invalid API key"
}

Not found error

{
  "detail": "Parsing not found."
}

Validation error

Validation errors may use detail, field names, or both.

{
  "detail": "Missing or invalid fields"
}

Or:

{
  "document": [
    "This field is required."
  ]
}

The schema describes validation errors as:

  • a string
  • or an array of strings
  • keyed by field name or detail

Documented HTTP status codes

These are the status codes explicitly documented in the public schema.

CodeMeaningWhere it appearsTypical handling
200Resource retrieved successfullylist and retrieve endpointsconsume response normally
201Resource created and processing startedcreate endpointsstore returned ID and continue
302Redirect to file download URLdocument downloadfollow redirect
400Missing or invalid request fieldscreate endpointsinspect validation payload and fix request
401Missing or invalid API keymost protected endpointsfix authentication
404Resource not foundretrieve and download endpointsverify the resource ID

The public schema does not currently document a broader catalog such as 403, 422, 429, or 5xx error payload shapes, so this page does not invent them.

By endpoint family

Documents

EndpointPossible documented errors
POST /v0/documents400, 401
GET /v0/documents401
GET /v0/documents/{id}401, 404
GET /v0/documents/{id}/download401, 404, 302 redirect on success

Parsings

EndpointPossible documented errors
POST /v0/parsing400, 401
GET /v0/parsing401
GET /v0/parsing/{id}401, 404

Extracts

EndpointPossible documented errors
POST /v0/extract400, 401
GET /v0/extract/{id}401, 404

Important distinction: HTTP errors vs resource failures

Some failures are returned as HTTP errors.

Other failures happen inside asynchronous resources after creation succeeds.

This is especially important for:

  • parsing
  • extract

A POST request may return 201, but the created resource can later end with:

  • parsing status: ERROR
  • extract status: ERROR

So for asynchronous resources, success of the initial HTTP request does not mean success of the processing job.

Handling parsing failures

Parsing has two kinds of failure signals:

1. Request-time validation errors

These return 400.

Common causes:

  • missing document
  • malformed JSON body
  • unsupported payload shape

2. Resource-time processing errors

These appear after the parsing resource has already been created.

You must inspect:

  • status
  • error

Possible terminal statuses:

  • FINISHED
  • PARTIAL_FINISHED
  • ERROR

Example failure-shaped parsing resource:

{
  "id": "PARSING_ID",
  "status": "ERROR",
  "error": "Unable to process the provided document."
}

Recommended handling:

  1. if POST /v0/parsing returns 400, fix the request
  2. if creation returns 201, poll /v0/parsing/{id}
  3. if the final status is ERROR, inspect the error field
  4. if the final status is PARTIAL_FINISHED, inspect pages_failed before deciding whether to continue

Handling extract failures

Extract also has two failure layers.

1. Request-time validation errors

These return 400.

Common causes:

  • missing schema
  • sending both document and parsing
  • malformed request body

2. Resource-time processing errors

These appear on the extract resource after a successful creation.

You must inspect:

  • status
  • error

Possible terminal statuses:

  • FINISHED
  • ERROR

Example failure-shaped extract resource:

{
  "id": "EXTRACT_ID",
  "status": "ERROR",
  "error": "Schema could not be applied to the current input."
}

Recommended handling:

  1. if POST /v0/extract returns 400, fix the request
  2. if creation returns 201, poll /v0/extract/{id}
  3. if the final status is ERROR, inspect the error field
  4. if output quality is wrong, inspect the upstream parsing before blaming the schema

Common issues

400: Missing or invalid fields

This usually means the request shape is wrong.

Typical causes by endpoint:

  • documents: missing file
  • parsing: missing document
  • extract: missing schema
  • extract: both document and parsing were sent

Solution:

  • inspect the validation payload
  • fix the request body or multipart form
  • retry with the corrected payload

401: Missing or invalid authentication

This means the API key is missing or invalid.

Solution:

  • ensure the X-API-Key header is present
  • ensure the key value is correct
  • ensure you are calling https://api.anesya.app

404: Resource not found

This means the referenced resource ID is missing or unknown to the current workspace context.

Typical causes:

  • wrong document ID
  • wrong parsing ID
  • wrong extract ID

Solution:

  • verify the UUID
  • verify that the resource was created successfully earlier
  • verify that your application is using the correct workspace credentials

302: Download redirect

This is not a failure.

It is the documented success behavior for document download.

Solution:

  • follow the redirect
  • or handle the redirected URL explicitly in your client

Handling errors in code

Even without a dedicated SDK-level error taxonomy documented here, a safe strategy is:

  1. check the HTTP status code
  2. parse the JSON response body if present
  3. inspect detail or field-level validation messages
  4. for asynchronous resources, poll and inspect status and error

cURL pattern

RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "https://api.anesya.app/v0/extract" \
  -H "X-API-Key: $ANESYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parsing": "YOUR_PARSING_ID",
    "schema": "YOUR_SCHEMA_ID"
  }')

STATUS=$(echo "$RESPONSE" | tail -n 1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [ "$STATUS" -eq 201 ]; then
  echo "Created: $BODY"
elif [ "$STATUS" -eq 400 ]; then
  echo "Validation error: $BODY"
elif [ "$STATUS" -eq 401 ]; then
  echo "Authentication error: $BODY"
elif [ "$STATUS" -eq 404 ]; then
  echo "Not found: $BODY"
else
  echo "Unexpected response $STATUS: $BODY"
fi

Application-level strategy

For create endpoints:

  • treat 201 as “resource created”, not “processing finished”

For retrieve endpoints:

  • treat 200 as “resource retrieved”
  • inspect status inside parsing or extract resources

For download:

  • treat 302 as success

The public documentation available here does not define an official retry matrix.

A conservative strategy is:

  • do not blindly retry 400
  • do not blindly retry 401
  • do not blindly retry 404
  • retry only after fixing the cause or when the input becomes valid

For asynchronous resources:

  • poll until a final state
  • if the final state is ERROR, inspect the resource-level error
  • only retry after correcting the input, schema, or upstream workflow

Troubleshooting checklist

When an Anesya request fails, check in this order:

  1. Is the X-API-Key header present?
  2. Is the request body valid JSON or valid multipart form-data?
  3. Are required fields present?
  4. If using IDs, do the referenced resources exist?
  5. If creating a parsing or extract, did you poll the created resource to a final state?
  6. If extract failed, does the upstream parsing look correct?
  7. If document download failed, did your client follow the redirect?
Previous page
Next page