Errors
Sphere uses traditional Http response codes to indicate the status of an API request.
Before reaching out to support with an error, please be aware that 99% of all reported errors are, in fact, user errors. Therefore, please carefully check your code before contacting Sphere support.
Error codes
Here is a list of the different categories of status codes returned by the Protocol API. Use these to understand if a request was successful.
- Name
200- Description
A 200 status code indicates that the operation was successful.
- Name
401- Description
A 401 status code indicates that a valid API key was not provided. problem.
- Name
403- Description
A 403 status code indicates that the credentials used for authentication lack the permissions necessary to make the request. problem.
- Name
404- Description
A 403 status code indicates that the requested resource could not be found. problem.
- Name
429- Description
A 429 status code indicates that the too many requests were sent to the API in a short period. It's recommended to slow down the request rate exponentially. problem.
- Name
5**- Description
A 5xx status code indicates a server error — you won't be seeing these.
Error types
Whenever a request is unsuccessful, the Sphere 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.
The following is an exhaustive list of the error types supported by the Sphere API.
- Name
customer/not-found- Description
This means that we made an error, which is highly speculative and unlikely.
- Name
customer/kyc-not-approved- Description
This means that you made an error, which is much more likely.
- Name
customer/tos-not-approved- Description
This means that you made an error, which is much more likely.
- Name
bankAccount/tos-v2-not-accepted- Description
This means that you made an error, which is much more likely.
- Name
bankAccount/missing-poa- Description
This means that you made an error, which is much more likely.
Error response
{
"ok": false,
"object": "error",
"error": "bankAccount/inactive",
"message": "bankAccount_7ab288f613f4443ab76630ed72b77470 is has inactive, but status active required.",
"data": null,
"request": "request_77414d59c7a042e586af6e13cbbe1660",
"ts": "2024-05-22T22:43:48.207Z",
}