Return to Orbital Homepage
API Documentation
Login to the Client Portal
Start typing to search…

Error Reference

This section provides an overview of potential error responses in Orbital Payments API.

200 - Success Response With a Failed Transaction (HPP Invoices Only)

In specific scenarios, particularly with Hosted Payment Page (HPP) invoice flows, the API might return a 200 OK response even though the subsequent transaction is expected to fail. When this occurs, the hppUrl returned in the response will include /transaction-failed:

https://hpp.getorbital.io/payment/deposit/transaction-failed

This indicates that while the invoice itself was successfully created, the payer will be directed to a failure screen if they attempt to proceed with the payment.

 Causes:

  • You've included an unsupported or disallowed currency for your account.
  • You provided a targetAmount without setting a validtargetCurrency, or vice versa.
  • Required Travel Rule fields (such as firstName, registeredName, or identificationType) are missing.

What to Do:

  • Carefully review the request parameters to ensure you are only using accepted values and supported currencies.
  • If your account requires Travel Rule compliance (e.g., for EU payers), ensure that all required identity fields are filled in correctly.
📘

This particular scenario is exclusive to HPP invoice flows. While the invoice creation itself is successful, the underlying payment transaction will not be completed.

400 - Validation & Client Errors

These errors occur when the request is malformed, missing required fields, or contains invalid values

Payins - Validation Errors

These are common validation errors you may encounter when creating invoices

Error Message

Cause

Solution

Missing required field: externalId

The externalId field was omitted.

Add a unique string to the externalId field.

duplicate externalId

You reused a previously submitted externalId.

Generate a new unique externalId for every transaction. Do not reuse IDs from previous attempts, even if the previous one failed or timed out.

The selected currency is invalid.

You used a value in the currency field that isn’t supported.

Check the currency parameter and ensure it uses one of the accepted values listed in the parameter description.

The targetCurrency is not supported.

The targetCurrency value you included is not accepted by the endpoint. This usually happens when you provide a crypto like ETH or BTC, or use a fiat currency that isn't supported

Use only accepted fiat currencies: USD, EUR, or GBP for the targetCurrency field.

The selected cashierCurrency is invalid.

You passed an invalid or unsupported value for cashierCurrency.

Check the cashierCurrency parameter in your request and use only accepted display currencies listed in the dropdown for your request.

The selected mainCurrency is invalid.

The blockchain network doesn’t match the stable coin.

For USDT and USDC, make sure your selected network is one of the accepted combinations.

The currency field is required.

currency was not included in the request.

Always include the currency field when you're converting funds. It defines the actual asset being debited from the payer.

targetCurrency - No correct currency for amount

This usually appears when:

– targetCurrency is provided without a matching targetAmount
– ortargetAmountis included withouttargetCurrency
` – or both are missing but a conversion is implicitly expected

Always pair targetCurrency with targetAmount. If you're not doing a conversion, remove both.


Payout - Validation Errors

These are common validation errors you may encounter when initiating a payout/withdrawal.

Error Message / TitleCauseHow to Fix It
The externalId field is required.You didn’t include the externalId field in your request. This field uniquely identifies each payout.Provide a unique externalId string in your request body.
duplicate externalIdThe externalId you provided has already been used in a previous payout.Generate a new unique externalId for every transaction. Do not reuse IDs from previous attempts, even if the previous one failed or timed out.
The address field is requiredYou didn’t provide the address where the funds should be sent. This field is mandatory.Include the receiver’s valid crypto wallet address in your request body. This field is mandatory for all payouts.
Address not validThe address provided is not a valid wallet address format or doesn't match the expected pattern for the chosen blockchain network.Verify the wallet address format carefully. Ensure it precisely matches the expected pattern for the chosen targetCurrency .
balance too lowYour merchant wallet doesn't have enough balance in the selected sourceCurrency to process the payout.Top up your account and then retry the payout. Also take note of the minimum transaction amount that applies to each cryptocurrency.
The selected sourceCurrency is invalidThe sourceCurrency value you provided isn’t supported or is misspelled.Review the sourceCurrency parameter and use only the supported crypto and fiat currencies listed.
The selected targetCurrency is invalidThe targetCurrency isn’t accepted for payouts, either because it's not supported or because it’s a fiat currency (which isn’t allowed for withdrawals).targetCurrency supports only the cryptocurrencies listed in the parameter description. Fiat currencies are not allowed for payouts.

Travel Rule Validation Errors

These errors indicate issues with mandatory data provided for Travel Rule (TR) compliance.

Error Message / TitleCauseSolution
Travel rule validation failedOne or more required fields are missing or invalid.Check the invalidParams list for the missing fields. Field requirements depend on both the Travel Rule entity (PPOU or PPDL) and whether the payer is an individual or a corporate.
identificationType is invalid. Accepted values are: ...The value for identificationType does not match what’s allowed for the selected combination of PPOU/PPDL and individual/corporate.Use a valid identification values for the selected entity (PPOU or PPDL) and payer type (Individual or Corporate) based on identificationType type you choose.
firstName is required, lastName is required, registeredName is required......Missing required fields for TRAdd the missing required fields listed to ensure your payload is complete.

Binance Identity Validation

Error Message / TitleCauseSolution
Payee not found.This occurs during Binance payer verification and it indicates that the Binance Pay ID, email, or wallet address is invalid.Confirm and re-enter a valid Binance Pay ID or email.
account not foundThis occurs during Binance receiver verification and it indicates that the Binance account ID doesn’t exist.Ensure the account exists and is associated with the provided ID.

401 – Incorrect API Key Provided

This error indicates that the API key you're using in your request is invalid.

 Causes:

  • Your server’s IP address might not be added to the Allow List under your account settings.
  • There's a typo or an extra space in the key.
  • The key you're using has been deleted, deactivated, or expired.

What to do:

  • Double-check that you're using the correct API key for your specific environment (test vs. live).
  • Ensure the key is added correctly to the Authorization header of your request.
  • If you're unsure, generate a new key and update your integration accordingly.

403 - Forbidden

This error indicates that the endpoint path you are trying to access is incorrect or does not exist in the API.

 Causes:

  • Typos in the route (e.g., /crypto/deposit/invoices instead of /crypto/deposit/invoice).
  • Calling a route that no longer exists or has been removed.

What to do:

  • Refer to the documentation and verify the exact endpoint path (e.g., /crypto/deposit/invoice).

404 - Bad Request

This error signifies that the server was unable to process your request because it was not well-formed, usually due to syntax errors.

 Causes:

  • Malformed JSON body (e.g., missing commas, brackets, or quotes).
  • Sending an empty body when the endpoint expects structured input.
  • Invalid formatting sent by your code or an API client like Postman.

What to do:

  • Use a JSON validator to check the syntax of your request body.
  • Ensure your request body is not empty, unless the endpoint explicitly allows it.
  • Always set the Content-Type header to application/json and send valid JSON.
  • Review sample payloads in the API documentation and replicate their structure precisely.

500 – Internal Server Error

This means something went wrong on the server side while processing your request. In most cases, this is not a client error, but there are a few common triggers:

 Causes:

  • An externalId that was already used in a previous request was re-submitted.
  • You’re using a currency that isn’t enabled or allowed for your account.
  • An unhandled exception or downstream failure occurred during processing.

What to do:

  • Ensure you're using a unique externalId for each request
  • Confirm your account is fully configured and approved for the action you're trying to perform
  • Check that the currency, network, and entity combinations are valid and supported under your account

If the issue persists, contact support with the full request payload and error instance ID to help us investigate further