Skip to main content

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.

StatusMeansWhat to do
400 Bad RequestA 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 UnauthorizedThe 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 ForbiddenAuthenticated, 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 FoundThe 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 AllowedThe 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 ConflictThe 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 LargeThe 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 EntityThe 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 RequestsToo many requests from your IP address. See Rate limits.Wait Retry-After seconds, then retry.
500 Internal Server ErrorSomething 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 UnavailableA dependency is temporarily unavailable (idempotency_unavailable).Retry later with the same Idempotency-Key.
504 Gateway TimeoutThe 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" }
FieldIs
codeThe HTTP status, repeated.
messageA stable snake_case code to branch on, e.g. forbidden, bank_account_not_found.
detailsOnly 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:

CaseAnswer
A path that does not exist404 {"code":404,"message":"not_found"}
A method the path does not take405 {"code":405,"message":"method_not_allowed"}, with an Allow header listing the methods the path takes.
Still running after 30 seconds504 {"code":504,"message":"gateway_timeout"}
Something went wrong on our end500 {"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 limited429 {"code":429,"message":"rate limit exceeded"} (not snake_case).
The body is not valid JSON, or a value has the wrong type400 {"code":400,"errorCode":"Bad Request","message":"failed to parse request"}
A field is missing or out of range422 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:

CaseAnswer
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 named403 {"code":403,"message":"forbidden"}
The workspace is not active403 {"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 account403 {"code":403,"message":"account_frozen"}
The same three endpoints with no accountId in the query or the body, from a workspace-scoped key400 {"code":400,"message":"account_id_required"}

These refusals also answer a snake_case code, listed on each endpoint's page:

StatusmessageMeans
400kyb_id_document_type_unsupportedA business verification's idDocumentType is a document type other than ein. details names the field.
404counterparty_not_foundA bank withdrawal or its preview names a counterparty that does not exist or is not the account's.
404withdrawal_not_foundA crypto withdrawal to cancel does not exist.
409kyb_verification_lockedA business verification document is uploaded or deleted while the verification is in review or approved.
409kyb_owners_missingA business verification is requested with no owners.
409kyb_owner_not_approvedA business verification is requested while an owner's verification is not approved.
409wallet_already_existsThe account already has a wallet for this coin.
409wallet_address_in_useThe wallet's deposit address is already registered.
409crypto_operation_unsupportedThe provider the workspace uses for this coin cannot create wallets.
409banking_operation_unsupportedThe workspace's bank cannot do this operation (opening a bank account, deposit instructions, a withdrawal or its preview).
409bank_account_not_openedA bank withdrawal from an account whose bank account was never opened.
422counterparty_incompleteA 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:

HeaderIs
X-RateLimit-LimitThe number of requests the limit allows at once.
X-RateLimit-RemainingHow many you can still send right now.
X-RateLimit-ResetWhen the limit is full again, as a Unix timestamp in seconds.
Retry-AfterOn 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 message when 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, 503 and 504. Wait between attempts, and resend a write with the same Idempotency-Key so it is never run twice (see Safe retries).
  • Do not retry a 400, 401, 403, 404 or 422 unchanged: 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:

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!