Error model

The API returns standard HTTP statuses with a single JSON error envelope. Validation errors include per-field details, and domain errors include a machine-readable code.

How to branch your logic on a response:

Error envelope

{
  "error": "Bad Request",
  "message": "The request contains invalid parameters or malformed data",
  "code": 400,
  "details": [
    { "field": "email", "message": "Invalid email format" }
  ]
}

• error: a short error name (Bad Request, Unauthorized, Not Found…).
• message: a human-readable description.
• code: the HTTP status as a number.
• details: per-field errors (for 400 validation errors): field + message.

HTTP statuses

Machine-readable codes

In addition to the HTTP status, domain errors carry a machine-readable code, which is the most convenient thing to branch your logic on:

Handling errors

Check the response status and read code/details:

const res = await fetch(url, { headers });
if (!res.ok) {
  const err = await res.json();
  console.error(`${err.code} ${err.error}: ${err.message}`);
  for (const d of err.details ?? []) {
    console.error(`  ${d.field}: ${d.message}`);
  }
}

res = requests.post(url, headers=headers, json=body)
if not res.ok:
    err = res.json()
    print(f"{err['code']} {err['error']}: {err['message']}")
    for d in err.get("details", []):
        print(f"  {d['field']}: {d['message']}")

When to retry

• 5xx and network failures: retry with exponential backoff. Retry transfers with the same idempotencyKey so the payment isn't duplicated (see Idempotency).
• 400 / 422: don't retry blindly; fix the request using details.
• 403: this is a Policy Engine decision. Check reason and trace to see which policy blocked the request (see Policy Engine).

Common mistakes

Next steps