Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API. Mistakes happen, and sometimes they will be yours, not ours. Let's look at some status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support).

Before reaching out to support with an error, please be aware that all client errors are documented below. Therefore, please carefully check your code before contacting Virtoshi support.

Status codes

Here is a list of the different categories of status codes returned by the Virtoshi API. Use these to understand if a request was successful.

Name
2xx
Description
A 2xx status code indicates a successful response.
Name
4xx
Description
A 4xx status code indicates a client error — this means it's a you problem.
Name
5xx
Description
A 5xx status code indicates a server error — you hopefully won't be seeing these.

Error types

Whenever a request is unsuccessful, the Virtoshi API will return an error response with an error type and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

Here is a list of the error types supported by the Virtoshi API — use these to understand what you have done wrong.

Name
FailedAuthenticationError
Description
No valid API key was found for the request.
Name
RateLimitExceededError
Description
You're exceeding the rate limits, contact us to tailor a plan to your needs.
Name
PsbtParseError
Description
This means that we've been unable to decode the psbt field in the request. Ensure that it a valid base64 payload encoding a PSBTv1 or PSBTv2.
Name
FailedAddressNetworkCheckError
Description
One or more of the addresses provided in the addresses field were not valid mainnet addresses.
Name
FailedAddressDecodeError
Description
One or more of the addresses provided in the addresses field were not properly encoded or contained non standard scripts.
Name
FailedParsingInputError
Description
This means that we were unable to find a witness utxo or non witness tx inside your PSBT for one or more of the inputs.
Name
FailedParsingInputAddressError
Description
This means that we were unable to encode one or more of scriptPubKey inside the inputs to a standard address.
Name
FailedParsingOutputAddressError
Description
This means that we were unable to encode one or more of scriptPubKey inside the outputs to a standard address.

Error response

{
  "name": "FailedAuthenticationError",
  "msg": "Failed to find valid authorization token",
}