> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.emtelligent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emtelligent.com/_mcp/server.

# Errors

## Error responses

Every error response has the same shape:

```json
{
  "error": {
    "code": "document_too_large",
    "message": "documents[2].text exceeds 65536 bytes",
    "request_id": "req_5d1c0a7e9f3b2a4c6e8d"
  }
}
```

Branch on `code`, which is stable. `message` is for people and may change; it
names the field at fault and never repeats your content. The `request_id` is
also returned in the `X-Request-Id` header; quote it when contacting support.

| HTTP | `code`                                                                                                     | Meaning and what to do                                                                                                                             |
| ---- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `invalid_json`, `invalid_document`, `invalid_prompt`, `invalid_idempotency_key`                            | The request is malformed. The message names the field, e.g. `documents[2].text`                                                                    |
| 400  | `ambiguous_documents`                                                                                      | `document` was sent with other documents. Send it alone, or use `documents`                                                                        |
| 400  | `invalid_document`                                                                                         | Also: every note in the FHIR bundles was unreadable and there is no structured record                                                              |
| 400  | `duplicate_document_id`                                                                                    | Document ids must be unique across the job — including against the positions used for documents without an id                                      |
| 400  | `unknown_document_id`                                                                                      | A `document_metadata` key matches no document                                                                                                      |
| 400  | `unsupported_document`                                                                                     | A `prep_documents` line has a PDF but no text                                                                                                      |
| 400  | `invalid_fhir_bundle`                                                                                      | An item of `fhir_bundles` is not a readable FHIR R4 Bundle. The message names `fhir_bundles[i]`                                                    |
| 400  | `invalid_nlp_result`                                                                                       | An `nlp_results` file is not `emtellipro-json-2`, or a document in it has no text or is malformed. The message names `nlp_results[i].documents[j]` |
| 401  | `invalid_credentials`                                                                                      | The key is missing, unknown, expired or revoked, or lacks the `summarization:process` scope                                                        |
| 402  | `organization_suspended`                                                                                   | The organization is suspended. See [Billing](/platform/billing)                                                                                    |
| 404  | `not_found`                                                                                                | No such job for your organization, or it has expired                                                                                               |
| 409  | `idempotency_conflict`                                                                                     | That `Idempotency-Key` was already used with a different body                                                                                      |
| 409  | `not_ready`                                                                                                | The result was requested before the job finished                                                                                                   |
| 409  | `no_result`                                                                                                | The job failed or was canceled, so there is no result                                                                                              |
| 410  | `result_expired`                                                                                           | The result was already downloaded                                                                                                                  |
| 413  | `document_too_large`, `prompt_too_large`, `documents_too_large`, `too_many_documents`, `payload_too_large` | Over a [limit](/summarization/reference/limits)                                                                                                    |
| 422  | `request_validation`                                                                                       | A field has the wrong shape, or is not recognised. The message names the fields                                                                    |
| 429  | `rate_limited`                                                                                             | Over a rate or concurrency limit. Wait for the `Retry-After` seconds                                                                               |
| 500  | `internal_error`                                                                                           | An unexpected problem on our side. Retry with backoff, and quote the `request_id` if it persists                                                   |
| 503  | `temporarily_unavailable`                                                                                  | Retry with backoff                                                                                                                                 |

## Failed jobs

A job can fail after it was accepted. Its status is then `failed`, with a code:

```json
{ "id": "job_8f2c1d0e9b7a6c5d4e3f2a1b", "status": "failed",
  "error": { "code": "documents_too_long" }, … }
```

| `error.code`                                                        | Meaning and what to do                                                                                             |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `insufficient_credit`                                               | The organization does not have enough credit for this job                                                          |
| `document_too_long`, `documents_too_long`                           | Too much to summarize in one job. Send fewer or shorter documents                                                  |
| `processing_timeout`                                                | The job took too long. Resubmit; if it happens again, send fewer documents per job                                 |
| `processing_unavailable`, `processing_error`, `billing_unavailable` | A problem on our side. Resubmit, with the same `Idempotency-Key`; contact support with the job `id` if it persists |

**Failed jobs are not billed.**

## Retrying safely

Send an `Idempotency-Key` header (1–128 of `A–Z a–z 0–9 _ . : -`) with each
submission. Retrying with the same key and the same body within 24 hours returns
the original job, with `200`, instead of creating — and billing — a second one.
The same key with a different body is `409 idempotency_conflict`.

Retry `429` after `Retry-After`, and `503` and network errors with exponential
backoff. Do not retry `4xx` other than `429` without changing the request.