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.

Partner API 0.1.0-draft.3 · Draft contract · Sandbox and SDK availability require confirmation.