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


```json
{
  "detail": "Invalid API key"
}
```

### Not found error


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

### Validation error

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


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

Or:


```json
{
  "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.

| Code | Meaning | Where it appears | Typical handling |
|  --- | --- | --- | --- |
| `200` | Resource retrieved successfully | list and retrieve endpoints | consume response normally |
| `201` | Resource created and processing started | create endpoints | store returned ID and continue |
| `302` | Redirect to file download URL | document download | follow redirect |
| `400` | Missing or invalid request fields | create endpoints | inspect validation payload and fix request |
| `401` | Missing or invalid API key | most protected endpoints | fix authentication |
| `404` | Resource not found | retrieve and download endpoints | verify 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

| Endpoint | Possible documented errors |
|  --- | --- |
| `POST /v0/documents` | `400`, `401` |
| `GET /v0/documents` | `401` |
| `GET /v0/documents/{id}` | `401`, `404` |
| `GET /v0/documents/{id}/download` | `401`, `404`, `302` redirect on success |


### Parsings

| Endpoint | Possible documented errors |
|  --- | --- |
| `POST /v0/parsing` | `400`, `401` |
| `GET /v0/parsing` | `401` |
| `GET /v0/parsing/{id}` | `401`, `404` |


### Extracts

| Endpoint | Possible documented errors |
|  --- | --- |
| `POST /v0/extract` | `400`, `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:


```json
{
  "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:


```json
{
  "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


```bash
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


## Recommended retry behavior

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?


## Related guides

* [API quickstart](/tutorials/quickstart)
* [Documents](/tutorials/documents)
* [Parsing](/tutorials/parsing)
* [Extract](/tutorials/extract)
* [Quickstart polling flow](/tutorials/quickstart)
* [Anesya API Reference for Coding Agents](/tutorials/agent-guide)
* [API reference](/api/schema)