Errors

Shape

{
  "error": "Human-readable message",
  "details": []   // optional; present on validation failures
}

Status codes

• 400 — invalid body (Zod validation). Check details.
• 401 — missing/invalid/revoked Bearer key, or merchant profile missing.
• 404 — escrow reference not found for this key.
• 409 — state conflict (e.g. deliver while not funded; release before seller accepted).
• 429 — rate limited. Honor Retry-After and retry_after_seconds.
• 5xx — server or payment-provider failure. Safe to retry initiate with the same reference.

Retry guidance

• initiate — always retry with the same reference (idempotent).
• deliver — safe to retry; returns already_delivered: true if set.
• release — safe to retry; returns already_released: true if done.