Errors
Every EDFlow error code: request-level HTTP status on the signed ingest profile, per-event result codes, and REST API problem details (RFC 9457) with retryable flags and the retry action to take first.
REST API: problem details
Every non-2xx response on /v1/* is application/problem+json (RFC 9457):
{
"type": "https://…/problems/insufficient_scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This operation needs the requests:write scope. Your token has: requests:read encounters:read.",
"code": "insufficient_scope",
"requestId": "rid_01J8ZQ4M2B7V6T1K9C3X5N0P8R",
"retryable": false,
"requiredScopes": ["requests:write"]
}- Switch on
code, never on the text. retryablesays whether a retry can succeed;retryActionsays what to do first:reauthenticate(new token),resign(new timestamp, delivery id and signature) orwait(honourRetry-After).- Validation failures add
errors[]with JSON Pointer paths. detailnever echoes secrets, tokens, visit numbers or payload values.- FHIR routes return an
OperationOutcomewhen you ask forapplication/fhir+json; raw HL7 returns an ACK (see HL7 v2); the OAuth endpoints use RFC 6749 error bodies. - Quote
requestIdin support tickets.
Request-level errors
| HTTP | Codes | Retryable | Do this |
|---|---|---|---|
| 400 | invalid_request, malformed_json, invalid_cursor, idempotency_key_required, site_required, batch_too_large | No | Fix the request |
| 401 | unauthenticated, invalid_token, token_revoked, wrong_environment, mtls_required | No | Fix the credential or host |
| 401 | token_expired | Yes, reauthenticate | New token, same request |
| 401 | missing_signature, invalid_signature, unknown_source (signed profile) | No | Check the key, version and body bytes |
| 401 | timestamp_out_of_window, delivery_replayed (signed profile) | Yes, resign | Re-sign with a new timestamp and delivery id |
| 403 | insufficient_scope, site_not_allowed, capability_disabled, ip_not_allowed, client_disabled, org_suspended, source_disabled | No | See detail |
| 404 | not_found | No | Unknown route or resource, or a resource at another site |
| 405, 406 | method_not_allowed, not_acceptable | No | |
| 409 | idempotency_in_progress | Yes, after a short wait | The same key is still running |
| 409 | idempotency_conflict, conflict | No | Event id reused with a different payload; or a state conflict |
| 410 | gone | No | Past its sunset date |
| 413, 415 | payload_too_large, unsupported_media_type | No | Split or fix the content type |
| 422 | validation_failed, idempotency_key_reused, event_rejected, processing_id_not_allowed, phi_suspected, transaction_not_supported, unsupported_encoding | No | Fix and resend |
| 429 | rate_limited | Yes, wait | Honour Retry-After |
| 500 | internal_error | Yes, with backoff | Quote the requestId |
| 503 | unavailable | Yes, wait | Keep it queued; honour Retry-After |
Per-event result codes
Inside a 200 batch response, each event has its own result. Rejected events carry one of these codes and a path:
| Code | Retryable | Cause |
|---|---|---|
invalid_envelope | No | Envelope field missing or malformed, or an id containing an identifier |
unsupported_spec_version | No | specVersion isn't supported |
unknown_event_type | No | Not in the catalogue |
event_type_not_allowed, site_not_allowed, source_kind_not_allowed | No | Your source isn't allowed to send it |
simulator_disabled | No | Simulator events outside a synthetic deployment |
encounter_required | No | The type needs encounter |
invalid_data | No | data failed validation; path points at the field |
prohibited_field | No | A prohibited key anywhere in the event |
idempotency_conflict | No | The id was used with a different payload |
occurred_at_in_future, occurred_at_too_old | No | More than 10 minutes ahead, or more than 90 days old |
processing_error | Yes | Transient; resend that event (same id) later |
The product's error catalogue
Errors raised by the product itself, with the text people see:
| Code | Group | What people see |
|---|---|---|
unauthenticated | Core | — |
forbidden | Core | You don't have access to this page. Ask your ED manager if you need it. |
not_found | Core | We couldn't find this page. |
not_opened | Core | — |
invalid_argument | Core | — |
out_of_range | Core | — |
rate_limited | Core | — |
conflict | Core | Someone else changed this. Review their changes and try again. |
access_ended | Core | — |
read_only | Core | — |
identity_unconfirmed | Core | — |
mfa_required | Core | — |
mfa_enrolment_required | Core | — |
session_locked | Core | — |
reauth_required | Core | — |
forbidden_in_production | Core | — |
sharing_unavailable | Core | — |
limit_reached | Core | — |
code_category_cannot_notify | Core | — |
invalid_transition | Core | — |
undo_expired | Core | — |
last_manager | Core | — |
approver_is_editor | Core | — |
content_not_ready | Core | — |
key_version_limit | Core | — |
key_already_revealed | Core | — |
provider_not_configured | Core | — |
password_policy | Core | — |
invalid_code | Core | — |
flow_disabled | Core | — |
forbidden_demo | Core | — |
approval_required | Core | — |
self_approval | Core | — |
verification_required | Core | — |
verification_failed | Core | — |
device_limit | Core | — |
owner_only | Core | — |
updates_paused | Core | — |
station_required | Core | — |
budget_exhausted | Core | — |
conflict_of_interest | Core | — |
policy_violation | Integration platform | — |
sod_violation | Integration platform | — |
affiliation_pending | Integration platform | — |
attestation_required | Integration platform | — |
app_not_approved | Integration platform | — |
in_use | Integration platform | — |
ai_disabled | AI features | — |
ai_unavailable | AI features | — |
ai_rate_limited | AI features | — |
ai_budget_exhausted | AI features | — |
ai_input_too_long | AI features | — |
ai_blocked | AI features | — |
ai_approval_invalid | AI features | — |
ai_approval_expired | AI features | — |
ai_region_violation | AI features | — |
ai_language_not_ready | AI features | — |
ai_governance_incomplete | AI features | — |
ai_sample_unscrubbable | AI features | — |
ai_sample_not_synthetic | AI features | — |
ai_audio_too_long | AI features | — |
ai_opted_out | AI features | — |
ai_query_refused_differencing | AI features | — |
ai_review_conflict | AI features | — |
ai_brand_mismatch | AI features | — |
Related
Last updated on