Error Reference

API response format

All successful responses follow this shape. meta is present only on paginated list endpoints.

Success

{
  "success": true,
  "data": { ... },
  "meta": { "page": 1, "per_page": 20, "total": 45, "total_pages": 3 }
}

All error responses follow this shape:

Error

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable description"
  }
}

The messageis written to be actionable — it names the field or rule that failed, and often the fix. Read it; don't switch on it (messages can improve over time). Switch on the HTTP status and code instead.

HTTP status codes

Code	Meaning
200	Success
201	Created (e.g. payment link, bank account, withdrawal)
400	Bad Request — invalid input, business-rule violation, or invalid status transition
401	Unauthorized — invalid, missing, or inactive API key/token
403	Forbidden — you don't have permission (e.g. a user_id that isn't a party to the escrow)
404	Not Found — resource doesn't exist (or belongs to another merchant/environment), or no route matches the path
405	Method Not Allowed — the path exists but not with this HTTP method (e.g. POST on a GET endpoint)
409	Conflict — currently only on registration when the email is already taken
410	Gone — a hosted action link has expired
429	Too Many Requests — rate limited
500	Internal Server Error

Error codes

Code	When
`BAD_REQUEST`	Invalid input or a business rule refused the request — validation failures, invalid escrow status transitions, duplicate order_id, duplicate dispute, wrong-role action links. The message says which rule.
`UNAUTHORIZED`	Missing or invalid session token
`INVALID_API_KEY`	X-API-Key missing, invalid, or the merchant is inactive / not yet approved for live
`FORBIDDEN`	Authenticated, but not allowed — e.g. acting on another merchant's escrow, or a user_id that isn't a party
`NOT_FOUND`	The resource doesn't exist — including ids that belong to another merchant or the other environment — or the URL path matches no route (the message names the path)
`METHOD_NOT_ALLOWED`	The path exists with a different HTTP method — the message names the method you sent (405)
`EMAIL_TAKEN`	Registration with an email that already has an account (409)
`RESEND_TOO_SOON`	Verification code requested again too quickly
`RATE_LIMITED`	Too many requests — back off and retry (429)
`LINK_EXPIRED`	A hosted action link is past its expiry (410) — mint a new one
`INTERNAL_ERROR`	Something failed on Kashia's side — safe to retry idempotent requests