Errors, retries and pagination
The draft represents errors as application/problem+json, using RFC 9457 fields plus an ENO code, optional field errors and a requestId for support.
{
"type": "https://docs.eno.health/errors/validation_failed",
"title": "Invalid request",
"status": 422,
"code": "validation_failed",
"requestId": "synthetic-request-001",
"errors": [{ "field": "phone", "code": "invalid_e164", "message": "Use E.164 format." }]
}
Error type URLs above are draft identifiers; their deployment is not verified. Branch on status and stable code, not English message text. Log request IDs and safe metadata, not tokens, document bytes or clinical values.
Retry deliberately
| Response | Behavior |
|---|---|
| 400 / 422 | Correct input before retrying. |
| 401 | Renew authentication using the backend token flow. |
| 403 | Check scope, grant and delegation; do not retry blindly. |
| 404 | Resource is absent or not visible to this integration. |
| 409 | Inspect the conflict code: duplicate identity, revision mismatch and pending extraction require different recovery. |
| 412 | Re-read the ETag and reconcile before updating. |
| 413 / 415 | Use an enabled upload method or supported format. |
| 429 | Honor Retry-After and use bounded backoff with jitter. |
| 5xx | Retry eligible operations with bounded backoff and an unchanged idempotency key. |
Idempotency
The design intends a 24-hour create window. The original spec does not yet declare the header on every create; use each operation's documented contract and confirm coverage before launch. Newly proposed batch creation and symptom submission require a key.
Reuse a key for retries of the same operation and payload. Do not reuse it for different patient data. Different content under the same key should conflict, not overwrite a prior submission.
Pagination and concurrency
Cursor lists use limit, cursor, nextCursor and hasMore, with a draft maximum limit of 200. Treat cursors as opaque and keep filters unchanged between pages. Stop when hasMore is false.
User updates support optional If-Match in the current draft. Omitting it does not prevent lost updates. Broader write-concurrency requirements remain a launch decision; do not assume every PATCH enforces optimistic locking.