Errors & idempotency

Error format

Errors come back in one of two JSON envelopes. Branch on the HTTP status first and the machine-readable code second, never on the human-readable message. Log the request_id so support can trace the call; responses also carry it in the X-Request-ID header.

Platform envelope

Used on every endpoint for authentication failures, request validation, missing resources and server errors. Here error is an object, and docs_url links to the code's entry on this page.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "1 validation error(s) in request",
    "request_id": "7c41e0b2",
    "docs_url": "https://mandatelabs.ai/docs/errors#VALIDATION_ERROR",
    "details": {
      "errors": [
        {
          "field": "body -> country",
          "message": "String should have at least 3 characters",
          "type": "string_too_short"
        }
      ]
    }
  }
}

Onboarding envelope

The onboarding endpoints (/onboard, /principals and its sub-resources, /agents/{id}/mandates) report their business rules in a flat envelope: error is the code string, and the status is mirrored in the body. Validation and authentication failures on those endpoints still use the platform envelope.

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

One check handles both shapes:

body = resp.json()
err = body.get("error")
code = err["code"] if isinstance(err, dict) else err   # "VALIDATION_ERROR" or "idempotency_key_reuse"

const body = await resp.json();
const code = typeof body.error === "object" ? body.error.code : body.error;

HTTP status codes

The API uses conventional HTTP semantics. The onboarding envelope also mirrors the status in its body.

Error codes

Platform codes

Returned in error.code. The code is derived from the error message, so treat it as a hint and branch on the HTTP status first: the same code can occasionally appear with a status other than the one listed. When no more specific code applies, error.code is ERROR.

Onboarding codes

Returned as the error string in the onboarding envelope.

OAuth token errors

POST /api/v1/oauth/token follows RFC 6749 §5.2 instead of either envelope, for example {"error": "invalid_client", "error_description": "Client authentication failed."}. Codes: invalid_request (400, client_id or client_secret missing), unsupported_grant_type (400), and invalid_client (401, unknown id, wrong secret, or a credential that is no longer valid).

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, wait for the Retry-After seconds before retrying. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining so you can slow down before you hit the limit.
• Make retries safe. Send an Idempotency-Key header on the onboarding create POSTs and an idempotency_key in the body on /authorize; the original response is replayed. Other create endpoints (POST /agents, /mandates, /webhooks) take no key, so check whether a timed-out create succeeded before retrying it.
• 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