Errors

The Batch API uses standard HTTP status codes. Errors return application/problem+json (RFC 9457), except the token endpoint, which returns OAuth errors.

{
  "type": "https://docs.amorphous.health/errors/invalid-request",
  "title": "Invalid request",
  "status": 422,
  "detail": "Document content exceeds 1 MiB.",
  "instance": "/v1/data-engine/batches/7c9e6679-7425-40de-944b-e07fc1f90ae7/documents",
  "requestId": "req_...",
  "errors": [
    {
      "pointer": "/documents/0/content",
      "code": "payload_too_large",
      "detail": "Maximum inline document size is 1 MiB."
    }
  ]
}

Handle errors by status and errors[].code. detail is for people and can change.

Problem Fields

Field	Description
type	URI for the problem type
title	Short summary of status
status	HTTP status code
detail	Explanation for this occurrence
instance	Request path
requestId	Matches the Request-Id header
existingBatchId	On a create conflict, the batch that already uses externalReference
errors	Field errors, each with pointer, code, and detail

Status Codes

Status	Meaning
400 Bad Request	The body or query is malformed
401 Unauthorized	The token is missing, expired, or invalid
403 Forbidden	The token lacks a scope, the caller IP is not allowed, the organization is suspended, or a test token called /fhir/R4
404 Not Found	The ID does not exist for your organization
409 Conflict	The batch is in the wrong state, a retry does not match, externalReference is taken, or live processing is not enabled
413 Content Too Large	The body exceeds the route limit
415 Unsupported Media Type	The media type is not supported or does not match the document
422 Unprocessable Content	A field is invalid. See errors
429 Too Many Requests	Rate limited. Wait for Retry-After
503 Service Unavailable	Temporary failure. Retry with backoff

Document Errors

A failed document has error.code and error.message. The message is safe to show to users.

Code	Meaning
checksum_mismatch	The uploaded file does not match checksumSha256
content_missing	The file was never uploaded
unsupported_content	The file could not be read as its mediaType
conversion_empty	The file contains no text
pipeline_failed	Extraction failed
not_processed	The document was not processed in time

Token Errors

POST /oauth/token returns OAuth 2.0 errors (RFC 6749) as application/json.

{ "error": "invalid_client", "error_description": "Client authentication failed." }

error	Status	Meaning
invalid_request	400	grant_type is missing, or both Basic and an assertion were sent
unsupported_grant_type	400	grant_type is not client_credentials
invalid_scope	400	A scope is not granted to the client
invalid_grant	400	The assertion has no jti or reuses one
invalid_client	401	Unknown client, wrong secret, invalid assertion, or disabled client
temporarily_unavailable	429	Too many requests or failed attempts. Wait for Retry-After