Error Handling
Common HTTP Status Codes
The BlockWyre API answers with standard HTTP status codes. Every error status comes with a JSON body, on /v3 and on /api/v2; see Error bodies.
| Status | Means | What to do |
|---|---|---|
400 Bad Request | A parameter, header or body is missing or malformed (failed to parse request, account_id_required, idempotency_key_required, …). | Fix the request. Sent again unchanged, it fails the same way. |
401 Unauthorized | The request is not authenticated as a caller this endpoint takes: the key, the signature or a claim failed, or the endpoint does not take this kind of key. | See 401 or 403. |
403 Forbidden | Authenticated, but not allowed (forbidden). On /api/v2: the endpoint is outside the API Key role, or an account-scoped key called a workspace operation. On both versions: an account-scoped key named another account. On /v3, an endpoint a key may not call answers 401 instead. A frozen account's money-out answers account_frozen. | See 401 or 403. |
404 Not Found | The resource does not exist. For an account-scoped key, another account's resource also reads as 404. A path that does not exist answers not_found. | Check the id, the account and the path. |
405 Method Not Allowed | The path exists, but not with this method (method_not_allowed). The Allow header lists the methods it takes. | Check the method on the endpoint's page. |
409 Conflict | The request conflicts with the resource's current state (customer_email_exists), or the same Idempotency-Key is still running (idempotency_in_progress). | Read the message. For idempotency_in_progress, retry after Retry-After seconds with the same key. |
413 Payload Too Large | The body is over the size limit (body_too_large, idempotency_body_too_large). | Send a smaller body. Signed bodies are limited to 1 MiB on /v3 and 33 MiB on /api/v2. |
422 Unprocessable Entity | The body parsed, but a field is missing or out of range (Validation failed, with details); the request breaks a business rule (for example insufficient_balance); or an Idempotency-Key was reused for a different request (idempotency_key_conflict). | Fix the fields details names, check the message, or use a new key for a new request. |
429 Too Many Requests | Too many requests from your IP address. See Rate limits. | Wait Retry-After seconds, then retry. |
500 Internal Server Error | Something went wrong on our end (internal server error). | Retry with backoff, sending the same Idempotency-Key on a write. If it persists, report it to support@blockwyre.com with the time, method and path. |
503 Service Unavailable | A dependency is temporarily unavailable (idempotency_unavailable). | Retry later with the same Idempotency-Key. |
504 Gateway Timeout | The request was still running after 30 seconds and was stopped (gateway_timeout). | The operation may still have run: retry a write with the same Idempotency-Key, so it is not run twice. |
Each endpoint's page lists the errors it answers, with their message.
Error bodies
v3
A /v3 error answers with this body:
{ "code": 404, "message": "bank_account_not_found" }
| Field | Is |
|---|---|
code | The HTTP status, repeated. |
message | A stable snake_case code to branch on, e.g. forbidden, bank_account_not_found. |
details | Only when there is more to say, e.g. the fields a 422 validation failure names. |
Some errors also carry errorCode, the HTTP status text ("Bad Request"). Branch on message, not on errorCode.
A few answers are the same whatever the endpoint, on /v3 and on /api/v2:
| Case | Answer |
|---|---|
| A path that does not exist | 404 {"code":404,"message":"not_found"} |
| A method the path does not take | 405 {"code":405,"message":"method_not_allowed"}, with an Allow header listing the methods the path takes. |
| Still running after 30 seconds | 504 {"code":504,"message":"gateway_timeout"} |
| Something went wrong on our end | 500 {"code":500,"errorCode":"Internal Server Error","message":"internal server error"} (not snake_case). A few name the check that could not run instead ("authorization check failed"). The body never says what went wrong. |
| Rate limited | 429 {"code":429,"message":"rate limit exceeded"} (not snake_case). |
| The body is not valid JSON, or a value has the wrong type | 400 {"code":400,"errorCode":"Bad Request","message":"failed to parse request"} |
| A field is missing or out of range | 422 with "message": "Validation failed" and the fields in details, below. |
{
"code": 422,
"errorCode": "Unprocessable Entity",
"message": "Validation failed",
"details": [{ "field": "body.email", "message": "email must be a valid email address" }]
}
v2
/api/v2 errors use the same fields as v3. Authentication, authorization and the account checks answer snake_case codes, as v3 does:
| Case | Answer |
|---|---|
| Not authenticated: the key, the signature or a claim failed, in either signing format (including the deprecated v2 format) | 401 {"code":401,"message":"unauthorized"} |
| Authenticated, but not allowed: outside the API Key role, a workspace operation with an account-scoped key, or another account named | 403 {"code":403,"message":"forbidden"} |
| The workspace is not active | 403 {"code":403,"message":"workspace_inactive"} |
A withdrawal or a trade (POST /api/v2/banking/withdrawal, POST /api/v2/crypto/withdraw, POST /api/v2/trade/execute) for a frozen or blocked account | 403 {"code":403,"message":"account_frozen"} |
The same three endpoints with no accountId in the query or the body, from a workspace-scoped key | 400 {"code":400,"message":"account_id_required"} |
These refusals also answer a snake_case code, listed on each endpoint's page:
| Status | message | Means |
|---|---|---|
400 | kyb_id_document_type_unsupported | A business verification's idDocumentType is a document type other than ein. details names the field. |
404 | counterparty_not_found | A bank withdrawal or its preview names a counterparty that does not exist or is not the account's. |
404 | withdrawal_not_found | A crypto withdrawal to cancel does not exist. |
409 | kyb_verification_locked | A business verification document is uploaded or deleted while the verification is in review or approved. |
409 | kyb_owners_missing | A business verification is requested with no owners. |
409 | kyb_owner_not_approved | A business verification is requested while an owner's verification is not approved. |
409 | wallet_already_exists | The account already has a wallet for this coin. |
409 | wallet_address_in_use | The wallet's deposit address is already registered. |
409 | crypto_operation_unsupported | The provider the workspace uses for this coin cannot create wallets. |
409 | banking_operation_unsupported | The workspace's bank cannot do this operation (opening a bank account, deposit instructions, a withdrawal or its preview). |
409 | bank_account_not_opened | A bank withdrawal from an account whose bank account was never opened. |
422 | counterparty_incomplete | A bank withdrawal to a counterparty without the account number ACH and domestic wire need. |
Other v2 errors still answer a human-readable sentence in message rather than a code, e.g. {"code":404,"message":"account not found"}. Validation failures answer 422 with "message": "Validation failed" and details.
Rate limits
Every API route, on /v3 and /api/v2, is limited per client IP address, not per key: every key used from the same IP shares one allowance. It admits up to 100 requests back to back and refills one request every 0.6 seconds, so 100 requests per minute sustained. Each counted response carries:
| Header | Is |
|---|---|
X-RateLimit-Limit | The number of requests the limit allows at once. |
X-RateLimit-Remaining | How many you can still send right now. |
X-RateLimit-Reset | When the limit is full again, as a Unix timestamp in seconds. |
Retry-After | On a 429 only: seconds to wait before retrying. |
A request over the limit answers 429 {"code":429,"message":"rate limit exceeded"} and is not run.
Best Practices
- Branch on the status and on
messagewhen it is a code (every v3 error, and the v2 codes above), never on the wording of a v2 sentence. - Retry only what can succeed on a retry:
409 idempotency_in_progress,429,500,503and504. Wait between attempts, and resend a write with the sameIdempotency-Keyso it is never run twice (see Safe retries). - Do not retry a
400,401,403,404or422unchanged: it fails the same way. - Report unexpected errors or inconsistencies to support@blockwyre.com.
Support and Resources
If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.
Stay Updated
Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:
- Instagram: BlockWyre Instagram
- Twitter: BlockWyre Twitter
- Facebook: BlockWyre Facebook
- LinkedIn: BlockWyre LinkedIn
We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!