---
title: Errors
description: Error fields, status codes, causes, and recovery actions.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Errors

A failed request returns an HTTP status and a JSON error object. Use the machine-readable code for application behavior and the request ID for diagnosis.

## Error envelope

**409 Conflict**

```json
{
  "error": {
    "code": "collection_not_ready",
    "message": "No file in the collection is ready yet. Try again.",
    "request_id": "req_example_not_ready",
    "retryable": true,
    "details": {
      "retry_after_seconds": 15
    }
  }
}
```

| Field | Type | Meaning |
| --- | --- | --- |
| `error` | object | The error envelope. |
| `error.code` | string | Stable machine-readable reason for the failure. |
| `error.message` | string | Human-readable explanation. Do not parse this text for program logic. |
| `error.request_id` | string | Correlation ID for this failed request. |
| `error.retryable` | boolean | Whether another attempt can succeed without correcting the underlying request. |
| `error.details` | object of JSON values | Additional context, such as retry_after_seconds, a field, or a limit. Can be empty. |

## Status and code catalog

| HTTP | Code | Cause | What to do |
| --- | --- | --- | --- |
| 400 | `invalid_request` | A request field, body, or query is invalid. | Correct the request using the endpoint schema. Unknown fields are rejected. |
| 400 | `invalid_cursor` | The cursor expired or does not belong to this request. | Restart from the first page with the intended request and key. |
| 400 | `invalid_uri` | The source URI is invalid or its scheme is unsupported. | Check URI syntax and storage.schemes from /info. |
| 400 | `invalid_filter` | A filter uses an invalid field, operator, or value. | Check error.details and the supported filter grammar. |
| 401 | `unauthenticated` | No valid API key was supplied. | Send a valid key. Replace a revoked or incorrect secret. |
| 403 | `forbidden` | The visible resource is outside the key’s allowed actions. | Use a key with the required action. |
| 404 | `not_found` | The resource is missing or outside the key’s resource scope. | Check both the identifier and the key’s namespace or collection scope. |
| 409 | `already_exists` | A unique resource name conflicts. | Use exist_ok where supported, or choose another name. |
| 409 | `idempotency_conflict` | An idempotency key was reused with a different body. | Retry with the original body or use a new key for a new operation. |
| 409 | `collection_empty` | Query has no files to use. | Add content and wait until it is ready. |
| 409 | `collection_not_ready` | No content is ready for the requested retrieval. | Wait for processing, or correct failed files when retryable is false. |
| 409 | `operation_in_progress` | Another operation conflicts with this write. | Wait for its job to finish before submitting another operation. |
| 409 | `limit_exceeded` | A resource or request value exceeds a size limit. | Reduce the value or resource count described by the error. |
| 409 | `external_source` | Engine cannot provide a download URL for this source. | Retrieve original bytes through your authorized storage service. |
| 413 | `request_too_large` | The JSON request exceeds 1,048,576 bytes. | Reduce the body or use an upload or supported URI for file content. |
| 422 | `storage_unreachable` | The cluster cannot read the source object. | Check object existence and the cluster’s storage access. |
| 429 | `rate_limited` | The cluster rejected request volume. | Delay retries and reduce concurrent requests. |
| 500 | `internal_error` | An unexpected server failure occurred. | Retain request_id for diagnosis. Recover current state before repeating a write. |
| 503 | `temporarily_unavailable` | Required capacity or a dependency is unavailable. | Honor retry guidance and retry with the same idempotency key when applicable. |

Operation pages list the errors relevant to that request. Scope errors can occur before resource validation. A namespace key receives 404 for another namespace, and a collection key receives 404 for an unnamed collection.

## Retry and recover

Inspect `retryable` and any `retry_after_seconds` in `details`. Fix invalid parameters and insufficient permissions before retrying. Wait for completion events when a collection or job is still processing.

A network timeout does not prove a write failed. For an operation that requires idempotency, retry the same body with the same `Idempotency-Key`. For accepted work, retain the job ID and recover its state with one GET.

Use a bounded retry policy for transient failures. Keep the request ID when reporting a problem. The [pagination and idempotency contract](/engine/reference/pagination) explains replay behavior.

## Failures after acceptance

An operation can fail after a `202` response. The failure then appears in the job’s `error` and can appear in the file’s `error`. Receive events, then read the resource for its current failure details.

An empty Search result is not always an error. Check `warnings` to distinguish no matches from a collection whose files failed. Query on an empty collection returns `collection_empty`.
## Sitemap

See the full [sitemap](/sitemap.md) for all pages.