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",
}

Was this page helpful?