Errors | emtelligent Documentation

Error responses

Every error response has the same shape:

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

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