Errors & idempotency

Error format

Every error returns a single, uniform JSON envelope. Branch on the machine-readable error field, not on the human-readable message — and log the request_id so support can trace the call.

{
  "error": "<code>",        // stable, machine-readable code
  "message": "…",          // human-readable explanation
  "status": 422,           // HTTP status, mirrored in the body
  "request_id": "req_…"      // correlate with support / logs
}

For example, reusing an Idempotency-Key with a different body returns:

{
  "error": "idempotency_key_reuse",
  "message": "Idempotency-Key was reused with a different request body.",
  "status": 422,
  "request_id": "req_8sZc1pQ2"
}

HTTP status codes

The API uses conventional HTTP semantics. The status is also mirrored inside the error envelope.

Error codes

The error field carries a stable machine code. The onboarding API in particular maps its business rules to these codes; build your error handling against them.

Idempotency

The onboarding create endpoints — POST /onboard, POST /principals, POST /principals/{id}/agents, and POST /agents/{id}/mandates — accept an Idempotency-Key header so a retried request can't create a duplicate.

• Retry with the same key + same body → the original response (status and body) is replayed. No second Principal, Agent, or Mandate is created.
• Same key + a different body → 422 idempotency_key_reuse. A key is bound to the exact request that first used it.
• Scope & retention → keys are scoped per Client and retained for roughly 24 hours, after which a key may be reused for a new operation.

Use a fresh UUID per logical operation — generate it once for the operation, reuse it across network retries of that same operation, and never recycle it for a different payload.

curl -X POST https://api.mandatelabs.ai/api/v1/principals \
  -H "X-API-Key: mdt_live_…" \
  -H "Idempotency-Key: 8f1c2e3a-9b7d-4f60-a1c2-2d3e4f5a6b7c" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_kind": "merchant",
    "program_ids": ["prg_…"],
    "client_customer_ref": "acme-001",
    "profile": { "display_name": "Acme Corp", "email": "[email protected]", "country": "US" },
    "verification": {
      "type": "KYB", "mode": "client_attested",
      "attestation": { "attested_by": "[email protected]", "scope": "Tier-2 CDD",
        "statement": "Acme performed CDD on this merchant", "evidence_ref": "case-123" }
    }
  }'

# Re-sending the identical request with the SAME Idempotency-Key
# replays the original 201 response — no duplicate Principal is created.

Retries & rate limits

A simple, safe policy:

• Retry 5xx and 429 with exponential backoff and jitter. For 429, respect any Retry-After hint before retrying.
• Always send an Idempotency-Key on create POSTs so those retries can't duplicate work — the original response is replayed.
• Do not blindly retry 4xx — they are terminal and indicate a request you must fix (bad input, missing scope, conflict). The one exception is an idempotent replay of the same create request, which is always safe.
• Cap retries (e.g. 3–5 attempts) and surface the request_id in your logs and any support tickets.

Next steps