All services report failures through the same envelope, so you can handle errors
uniformly regardless of which endpoint you called.
Error shape
{
"status": false,
"message": "Wallet not found"
}
errors array of field-level messages:
{
"status": false,
"message": "Validation failed",
"errors": [
"webhookUrl: Invalid url"
]
}
| Field | Type | Description |
|---|
status | boolean | Always false on error. |
message | string | Human-readable error summary. |
errors | string[] | Optional. Per-field validation messages (field: message). |
Token endpoint is differentPOST /v1/oauth/token returns OAuth 2.0 error bodies ({ "error", "error_description" })
rather than this envelope. See Authentication. Status codes
| Status | Meaning | Typical cause |
|---|
200 OK | Success | Request completed. |
201 Created | Created | A new resource (subscription, transfer) was created. |
202 Accepted | Accepted | Work was queued (e.g. webhook resend). |
400 Bad Request | Invalid input | Malformed parameter, body, or unsupported value. |
401 Unauthorized | Not authenticated | Missing/invalid token, or missing project/business context. |
402 Payment Required | Insufficient funds | Wallet balance cannot cover estimated gas. |
403 Forbidden | Not authorized | Test token used, missing capability, or cross-business access. |
404 Not Found | No such resource | Unknown id, or a resource not owned by your project. |
422 Unprocessable Entity | Semantic failure | Validation passed but the operation failed (e.g. transfer reverted). |
429 Too Many Requests | Rate limited | Throttle exceeded; honour retryAfter. |
503 Service Unavailable | Upstream issue | Dependency (e.g. gas pricing) temporarily unavailable — retry. |
Common error messages
| Status | Message | Where |
|---|
401 | Authorization token is missing or malformed. | Any guarded endpoint. |
401 | Invalid token | Token failed verification. |
401 | Token is missing project or business context | Token lacks the required claims. |
403 | Test tokens are not allowed, please use your live api key. | Business endpoints. |
403 | Missing required capability: <capability> | Indexer endpoints. |
403 | Unauthorized: Cannot access wallet from other business | Wallet endpoints. |
404 | <Resource> not found | Lookups by id. |
Retry strategyRetry 429 after the retryAfter interval, and retry 503 after a short backoff.
Do not retry 400, 401, 403, 404, or 422 without changing the request.
