Errors
API errors use standard HTTP status codes. Application-level failures also carry a stable
errorCode string so you can branch on the cause programmatically instead of parsing messages.
Response format
A failed request returns the matching HTTP status (400, 401, 404) with this body:
{
"message": "Session expired",
"errorCode": "SESSION_EXPIRED",
"error": "Bad Request"
}Branch on errorCode, not message. Messages are human-readable and may be reworded;
errorCode values are stable.
Session
errorCode | HTTP | When |
|---|---|---|
SESSION_NOT_FOUND | 404 | The sid doesn't exist. |
SESSION_EXPIRED | 400 | The session passed its TTL. Create a new session. |
SESSION_NOT_OPEN | 400 | The session was cancelled and can no longer be used. |
Withdrawals
A withdrawal is approved by your approval webhook (WITHDRAW_REQUEST). To
decline one, return an error with a numeric code — it maps to the errorCode the widget
surfaces to the user, all as HTTP 400:
Your numeric code | errorCode | Meaning |
|---|---|---|
1 | WITHDRAW_DECLINED | Generic decline (also the default if no code is given). |
2 | INSUFFICIENT_BALANCE | User lacks the balance for this amount. |
3 | WITHDRAW_UNAVAILABLE | Withdrawals temporarily unavailable. |
4 | USER_NOT_ELIGIBLE | User not permitted to withdraw. |
5 | DAILY_LIMIT_EXCEEDED | User hit their daily limit. |
6 | WITHDRAW_AMOUNT_TOO_LOW | Below your minimum. |
7 | WITHDRAW_AMOUNT_TOO_HIGH | Above your maximum. |
8 | ACCOUNT_VERIFICATION_REQUIRED | User must complete verification first. |
9 | WITHDRAW_SUSPENDED | Withdrawals suspended for this user. |
The API also returns one withdrawal error on its own, as HTTP 400:
errorCode | When |
|---|---|
WITHDRAW_IN_PROGRESS | A withdrawal for this session is already PENDING/PROCESSING. Wait for it to finish. |
Transaction limits
errorCode | HTTP | When |
|---|---|---|
AMOUNT_BELOW_MINIMUM | 400 | Amount under the configured minimum for the operation. |
AMOUNT_ABOVE_MAXIMUM | 400 | Amount over the configured maximum for the operation. |
Authentication
| HTTP | When |
|---|---|
401 | Missing or invalid Authorization: Bearer <OPERATOR_SECRET_KEY> on an operator endpoint. |