Idempotency and errors

Retry safely with idempotency keys, and read every error the same way.

Idempotency

Payer work has side effects: a call gets placed, a portal form gets submitted. Send an Idempotency-Key header on every POST so a retry after a timeout never does the work twice.

bash

-H "Idempotency-Key: $(uuidgen)"

Use a fresh UUID per operation, and reuse it only to retry that operation.
Daybook keeps keys for 24 hours. A repeat within that window returns the original response.
The same key with a different body returns 409 idempotency_conflict.

Errors

Every error has the same shape.

json

{
  "error": {
    "type": "invalid_request",
    "code": "missing_field",
    "message": "patient.member_id is required for claim_status calls.",
    "field": "patient.member_id",
    "request_id": "req_01JBXV2Q"
  }
}

Status	type	Meaning
`400`	`invalid_request`	A field is missing or wrong. `field` names it.
`401`	`authentication_failed`	Missing or wrong API key.
`404`	`not_found`	No such object for this key.
`409`	`conflict`	Idempotency conflict, or the object is in the wrong state (approving a task that isn't waiting).
`422`	`payer_rejected`	The payer or clearinghouse rejected the request. `code` carries the payer's reason, such as an AAA code.
`429`	`rate_limited`	Slow down. `Retry-After` says for how long.
`5xx`	`api_error`	Our side. Retry with the same idempotency key.

Quote the request_id when you contact us.

Money and dates

Amounts are integer cents (31200 is $312.00). Dates are YYYY-MM-DD; timestamps are RFC 3339 in UTC.