Errors and idempotency Docs

ReferenceUpdated May 28, 2026

Error shape

API errors return a stable code, message, request ID, and optional field-level details.

Error responsejson

{
  "error": {
    "code": "transfer_review_required",
    "message": "This transfer requires approval before submission.",
    "requestId": "req_01J0N0B9JG",
    "details": {
      "policyId": "pol_treasury_2of3"
    }
  }
}

Idempotency

Use a unique idempotency key for every create or submit operation. If your backend retries with the same key and payload, Mozaca returns the same resource instead of creating a duplicate.

Generate keys from your internal operation ID, not from the current timestamp alone.
Do not reuse the same key for different payloads.
Store the key beside the business operation in your database.

Retry guidance

Retry network timeouts and 5xx errors with backoff. Do not blindly retry validation errors, policy holds, or compliance review states.

Response	Retry	Action
400	No	Fix request payload
401 or 403	No	Check credentials and scopes
409	Maybe	Inspect idempotency or resource state
429	Yes	Back off and respect rate limit
5xx	Yes	Retry with the same idempotency key