Handle errors

When an API request fails, Bitvavo returns an HTTP status code and a JSON body with an errorCode and a description. Use the errorCode to identify the issue and resolve it.

Response format

Every error response includes an errorCode and an error message.

REST API error response
{
  "errorCode": 205,
  "error": "Invalid parameter: price"
}

WebSocket error responses use the same fields, wrapped in an event:

WebSocket error response
{
  "event": "error",
  "errorCode": 205,
  "error": "Invalid parameter: price"
}

HTTP 400: Bad Request

Request format errors

`errorCode`	Reason	Action
102	Your request contains invalid JSON.	Validate the JSON body before sending.
200	This endpoint does not accept path parameters.	Check the API reference for the correct request format.
201	This endpoint does not accept body parameters.	Check the API reference for the correct request format.
202	This `orderType` does not support the parameter you used.	Check the Create order endpoint for supported parameters.
203	Your request has missing or incompatible parameters.	Check required parameters in the API reference.
204	You used an invalid parameter for this endpoint.	Check the API reference for valid parameters.
205	You provided an invalid parameter value.	Check the API reference for accepted values.
206	You used incompatible parameters together.	Remove one of the conflicting parameters.

Order and trading errors

`errorCode`	Reason	Action
210	`amount` exceeds the maximum for this market.	Check market limits with Get markets.
211	`price` exceeds the maximum allowed.	Lower the `price` value.
212	`amount` is below the minimum for this market.	Check `minOrderInBaseAsset` with Get markets.
213	`price` is too low.	Increase the `price` value.
215	`price` has more than 15 decimal places.	Reduce to 15 or fewer decimal places.
216	Your balance is insufficient.	Check your account balance.
217	`amountQuote` is below the minimum for this market.	Check `minOrderInQuoteAsset` with Get markets.
219	This market is no longer listed on Bitvavo.	Check available markets with Get markets.
220	A `clientOrderId` with this value already exists in the market.	Use a unique value per market.
231	The market is paused and `timeInForce` is not `GTC`.	Set `timeInForce` to `GTC`.
232	You did not provide any changes.	Include at least one changed parameter when updating an order.
234	You cannot update a `market` order.	Cancel it and create a new order instead.
235	You exceeded the maximum of 100 open orders per market.	Cancel existing orders before placing new ones.
236	You used more than one of `amount`, `amountRemaining`, or `amountQuote`.	Use only one.
237	You omitted required parameters for the `stopLoss` order type.	Check the Create order endpoint for required parameters.
238	You omitted required parameters for the `stopLossLimit` order type.	Check the Create order endpoint for required parameters.
239	You cannot switch between `amount` and `amountQuote` during an update.	Cancel the order and create a new one instead.
422	The price does not align with the allowed tick size.	Get the `tickSize` for the market with Get markets.
429	A parameter value has too many decimal places.	Check the allowed precision for the market with Get markets.

Market status errors

You get these errors when you interact with a market that is not in trading status. Check the current market status with Get markets.

`errorCode`	Reason	Action
423	The market is halted due to maintenance, technical issues, or other operational reasons.	Wait for the market to resume trading.
424	The market is in `cancelOnly` status.	You can only cancel orders.
425	The market is in an auction phase.	Wait for trading to resume.
426	The market is in `auctionMatching` status.	Wait for the auction to complete.

Deposits and withdrawals errors

`errorCode`	Reason	Action
401	This asset does not support deposits.	—
402	You must verify your identity to deposit or withdraw assets.	Complete the verification process in your Bitvavo account.
403	You must verify your phone number to deposit or withdraw assets.	Verify your phone number in your Bitvavo account.
404	An internal error prevented the operation.	Retry the request. If the issue persists, contact Bitvavo support.
405	You cannot withdraw during the cooldown period.	Wait for the cooldown to expire before retrying.
406	`amount` is below the minimum allowed value.	Increase the `amount`.
407	You cannot make an internal transfer for this asset.	—
408	Your balance is insufficient.	Check your account balance.
409	Your bank account is not verified.	Verify your bank account and try again.
410	This asset does not support withdrawals.	—
411	You cannot transfer assets to yourself.	—
412	The deposit or withdrawal failed.	If the issue persists, contact Bitvavo support.
413	Your IP address is not in the whitelist.	Add it to your API key whitelist.
414	You cannot withdraw assets within 2 minutes of logging in.	Wait and try again.

HTTP 403: Forbidden

Authentication

`errorCode`	Reason	Action
300	This endpoint requires authentication.	Add authentication to your request.
301	Your API key has an invalid length.	Verify that you are using the correct key.
302	The timestamp is not in milliseconds.	Use Unix epoch time in milliseconds for `Bitvavo-Access-Timestamp`.
303	`Bitvavo-Access-Window` is out of the allowed range.	Set it to a value between 100 and 60000 milliseconds.
304	Bitvavo did not receive your request within the access window.	Sync your system clock or increase `Bitvavo-Access-Window`.
305	Your API key is not active.	Activate it in your Bitvavo account settings.
306	You have not confirmed your API key activation.	Check the confirmation email from Bitvavo.
307	Your IP is not in the whitelist for this API key.	Add your IP address to the key's whitelist.
308	Your signature format is invalid.	Review the authentication steps and verify your signature generation.
309	Your signature is invalid.	Verify that you sign `timestamp + method + url + body` correctly with your API secret. See authentication.

Permissions

`errorCode`	Reason	Action
310	Your API key does not have the Trade digital assets permission.	Enable it in your API key settings.
311	Your API key does not have the View access permission.	Enable it in your API key settings.
312	Your API key does not have the Withdraw digital assets permission.	Enable it in your API key settings.
313	Your Bitvavo session is invalid.	—
314	The VPC ID is invalid.	—
316	This WebSocket connection only supports public asset information.	—
317	Your account is locked.	Contact Bitvavo support.
318	You must verify your account before using the API.	Complete verification in your Bitvavo account.
319	This feature is not available in your region.	—
320	Operation forbidden.	Contact Bitvavo support.
511	You need the Administrative permission for this endpoint.	Contact Bitvavo support.
512	You need the Internal Transfer permission for this endpoint.	Contact Bitvavo support.
513	You need the Include all subaccounts permission for this endpoint.	Contact Bitvavo support.
514	You cannot use this request for subaccount management.	—

HTTP 404: Not found

`errorCode`	Reason	Action
240	The order does not exist or is no longer active.	Check the `orderId` and ensure no conflicting calls overlap.
415	Bitvavo does not recognize the WebSocket action.	Check the action name in the WebSocket API reference.
510	The API key is not linked to the subaccount, or the subaccount does not exist.	—

HTTP 409: Conflict

`errorCode`	Reason	Action
431	The market is in `halted`, `auction`, or `auctionMatching` status.	Wait for `trading` status.

HTTP 429: Too many requests

`errorCode`	Reason	Action
105	You exceeded the rate limit. Your account or IP address is temporarily blocked.	Wait until `bitvavo-ratelimit-resetat` (check the response headers) before sending new requests.
112	You exceeded the WebSocket rate limit for messages per second.	Reduce your message frequency.

HTTP 500: Internal server error

`errorCode`	Reason	Action
101	Unknown error. The service is not reachable.	Contact Bitvavo support.
400	Unknown server error.	Contact Bitvavo support.

HTTP 503: Service unavailable

`errorCode`	Reason	Action
107	Bitvavo is overloaded.	Retry after 500 ms.
108	Bitvavo encountered a processing issue.	Increase your `Bitvavo-Access-Window` or retry after 500 ms.
109	The request timed out. The operation may or may not have succeeded.	Check the state before retrying to avoid duplicates (for example, get the order before creating it again).
111	The matching engine is temporarily unavailable.	Retry after a short delay.
419	The server is unavailable.	Retry after a short delay.
430	The connection timed out because Bitvavo received no new market data events.	Check that the market is in `trading` status.

Handle retries

HTTP status	Retry?	Guidance
400	No	Fix your request. Check parameters, values, and formats.
403	No	Fix authentication or permissions. Check your API key, signature, and key settings.
404	No	Fix the resource reference (for example, `orderId` or WebSocket action name).
409	Wait	The market is not in `trading` status. Wait for the market status to change.
429	Yes, after delay	Wait until `bitvavo-ratelimit-resetat` before retrying. See rate limits.
500	Yes, after increasing delay	Retry after 500 ms, then 1 s, then 2 s, and so on. If the error persists, contact Bitvavo support.
503	Yes, after short delay	Retry after 500 ms. For `errorCode` 109, verify the operation state before retrying.

tip

For errorCode 109 (timeout), the operation may have already succeeded. Always check the current state (for example, get the order) before retrying to avoid duplicates.

Response format​

HTTP 400: Bad Request​

Request format errors​

Order and trading errors​

Market status errors​

Deposits and withdrawals errors​

HTTP 403: Forbidden​

Authentication​

Permissions​

HTTP 404: Not found​

HTTP 409: Conflict​

HTTP 429: Too many requests​

HTTP 500: Internal server error​

HTTP 503: Service unavailable​

Handle retries​

See also​