Errors
Sphere uses traditional HTTP response codes to indicate the status of an API request.
Status codes
Here is a list of the status codes returned by the Sphere API.
2xx
- Name
200
- Description
A 200 status code indicates that the operation was successful.
- Name
201
- Description
A 201 status code indicates that the operation was successful and a new resource was created.
4xx
- Name
400
- Description
A 400 status code indicates that server could not understand the request because of invalid syntax
- Name
401
- Description
A 401 status code indicates that request has not been applied because the server requires user authentication.
- Name
403
- Description
A 403 status code indicates that the credentials used for authentication lack the permissions necessary to make the request.
- Name
404
- Description
A 404 status code indicates that the requested resource could not be found.
- 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.
5xx
- Name
500
- Description
A 500 status code indicates a server error. Please, reach out to support if you see this.
Error types
When a API request is unsuccessful, we return a json 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.
When the API errors, the error
field contains an error type and the message
field contains a human-readable message. The following list contains an exhaustive list of Sphere error types.
Customer
- Name
customer/not-found
- Description
Customer not found
- Name
customer/duplicate
- Description
Customer with provided data already exists.
- Name
customer/kyc-not-approved
- Description
Customer's KYC/B has not been approved yet. Approval is required.
- Name
customer/tos-not-approved
- Description
Customer has not accepted Sphere's Terms of Service. Acceptance is required.
- Name
customer/tos-disclaimer-missing
- Description
Terms of Service has been marked as accepted, but disclaimer is missing or invalid.
- Name
customer/tos-v2-not-accepted
- Description
Sphere's Terms of Service v2 not accepted. Acceptance is required.
- Name
customer/missing-poa
- Description
Proof of address missing for EU KYC.
- Name
customer/missing-data
- Description
Data specified in error message is required, but hasn't been provided.
- Name
customer/unsupported-country
- Description
Country provided in address is not supported.
- Name
customer/unsupported-state
- Description
Provided United States state is not supported.
- Name
customer/unsupported-file-type
- Description
Type of file provided is not supported.
- Name
customer/invalid-business
- Description
You cannot attach a UBO customer to chosen business.
- Name
customer/ownership-mismatch
- Description
Selected resources must belong to same customer.
- Name
customer/not-supplied
- Description
No customer supplied.
- Name
customer/missing-operating-residency
- Description
Missing operating residency information for selected customer.
- Name
customer/restricted-country
- Description
Customer is from a restricted country, not allowed to continue.
- Name
customer/incomplete-onboarding
- Description
Customer has not completed onboarding.
- Name
customer/prohibited-business-type
- Description
Business of this typenot currently supported
- Name
customer/wrong-data-structure
- Description
Structure of provided data regarding source of funds for customer is incorrect.
Wallets
- Name
wallets/invalid-address
- Description
Invalid address for specified network.
- Name
wallets/unsafe-address
- Description
Unable to interact with this wallet.
- Name
wallets/unsupported-network
- Description
Provided network is unsupported.
- Name
wallets/duplicate
- Description
Wallet with this address already exists.
- Name
wallets/not-found
- Description
Provided wallet not found.
- Name
wallets/deleted
- Description
Provided wallet has been deleted.
- Name
wallets/missing
- Description
Parameter specified in error message is missing for wallet on provided network.
- Name
wallets/verified-wallet-error
- Description
Verified wallets have to be either customer or merchant owned.
- Name
wallets/no-signature-provided
- Description
No signature provided for creation of verified wallet.
- Name
wallets/invalid-signature
- Description
Provided signature is invalid.
Liquidation Wallets
- Name
liquidation/unwanted-data
- Description
Data specified in error message must not be provided.
- Name
liquidation/missing-data
- Description
Missing data specified in error message.
Address
- Name
address/invalid
- Description
Malformed address, missing required fields.
- Name
address/invalid-country
- Description
Country code provided is not compliant with ISO 3166-1 alpha-3.
- Name
address/invalid-state
- Description
State code provided is not compliant with ISO 3166-2.
- Name
address/country-state-mismatch
- Description
Provided state is not part of provided country.
Approval
- Name
approval/not-found
- Description
Approval not found.
- Name
approval/duplicate
- Description
Approval already exists.
Tax Rates
- Name
taxRate/not-found
- Description
Tax rate not found.
- Name
taxRate/mismatch
- Description
The tax rate does not match the paymentLink.
Shipping Rates
- Name
shippingRate/not-found
- Description
Shipping rate not found.
- Name
shippingRate/mismatch
- Description
The shipping rate does not match the paymentLink.
Bank Accounts
- Name
bankAccount/inactive
- Description
Specified bank account is inactive, active status required.
- Name
bankAccount/duplicate
- Description
Bank account has already been added before. Please input/select a different bank account instead.
- Name
bankAccount/ach-only
- Description
Only US ACH accounts are supported for Plaid connections. Please try again with a US ACH account.
- Name
bankAccount/customer-mismatch
- Description
Specified bank account does not belong to the given customer.
- Name
bankAccount/wrong-account-data
- Description
Either IBAN/BIC or accountNumber/routingNumber should be provided, not both.
- Name
bankAccount/missing-account-data
- Description
Both specified properties must be provided together.
- Name
bankAccount/too-long
- Description
Specified property number must be maximum specified length characters long.
- Name
bankAccount/wrong-format
- Description
Specified property number must contain only characters 0-9 and A-Z.
- Name
bankAccount/not-found
- Description
Bank account not found.
- Name
bankAccount/not-active
- Description
Bank account not active.
- Name
bankAccount/deleted
- Description
Bank account deleted.
Transfer
- Name
transfer/missing-data
- Description
Specified key is missing.
- Name
transfer/wrong-type
- Description
Could not infer transfer type from provided source and destination.
- Name
transfer/not-supported
- Description
Specified transfer property and value not supported.
- Name
transfer/limit-exceeded
- Description
Specified limit type per specified time frame exceeded.
- Name
transfer/max-fee-exceeded
- Description
Fee must not exceed specified maximum. Provided fee exceeds this limit.
- Name
transfer/invalid-fee
- Description
Fee must be a positive integer. Provided fee is invalid.
- Name
transfer/too-many-fees
- Description
There are too many fees. Please contact support.
- Name
transfer/invalid-fee-target
- Description
Target is not well formatted. Check setter/application/customer combination.
- Name
transfer/invalid-crypto
- Description
Provided currency is not a supported cryptocurrency.
- Name
transfer/fee-mismatch
- Description
Something went wrong when calculating fees. Expected and received amounts do not match.
- Name
transfer/maintenance-lock
- Description
Executing transfers for specified application locked for maintenance. This should not take longer than 10s. Please try again.
- Name
transfer/fee-not-found
- Description
Transfer fee not found for specified ID.
- Name
transfer/fee-not-active
- Description
Cannot deactivate, fee is already not active.
- Name
transfer/invalid-params
- Description
Invalid params provided.
- Name
transfer/invalid-bank-account-network
- Description
Invalid bank account network for specified transfer type.
- Name
transfer/bridge/source-deposit-instructions-not-found
- Description
Invalid parameters. Please check your request. We were unable to create the specified transfer type.
- Name
transfer/invalid-network-currency-pair
- Description
Invalid network-currency pair for specified endpoint type.
Transfer Tiers
- Name
transfer/invalid-level
- Description
Invalid payout tier level specified.
- Name
transfer/single-tx-size-limit-reached
- Description
Your current limit for this transfer is specified amount. Transfer limits are set dynamically based on activity within a rolling time period. If you'd like to request an increase in your transfer limit, please reach out to our team via the chat widget here.
- Name
transfer/tx-limit-reached
- Description
You have reached the maximum number of transfers allowed within a rolling time period. You'll be able to make another transfer on the specified date. If you'd like to request an increase in your transfer limit, please reach out to our team via the chat widget here.
- Name
transfer/volume-limit-reached
- Description
Your current limit for this transfer is specified amount. Transfer limits are set dynamically based on activity within a rolling time period. If you'd like to request an increase in your transfer limit, please reach out to our team via the chat widget here.
Applications
- Name
application/not-found
- Description
Application not found for specified ID.
- Name
application/earlyAccess
- Description
Specified application does not have early access.
- Name
application/custodialWalletAccess
- Description
Specified application does not have custodial wallet access.
- Name
application/transferAccess
- Description
Specified application does not have access to transfers.
- Name
application/creditCardAccess
- Description
Specified application does not have access to credit cards.
Plaid
- Name
plaid/not-individual
- Description
Specified customer is not an individual.
- Name
plaid/not-american-ssn
- Description
Specified customer does not have an American SSN.
- Name
plaid/not-american-phone
- Description
Specified customer does not have an American phone number.
- Name
plaid/missing-ip
- Description
Customer record does not have a valid IP address. Please resolve this by contacting support.
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",
}