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
, oridentificationType
) 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 |
---|---|---|
| The | Add a unique string to the |
| You reused a previously submitted | Generate a new unique |
| You used a value in the | Check the |
| The | Use only accepted fiat currencies: |
| You passed an invalid or unsupported value for | Check the |
| The blockchain network doesn’t match the stable coin. | For |
|
| Always include the |
| This usually appears when: – | Always pair |
Payout - Validation Errors
These are common validation errors you may encounter when initiating a payout/withdrawal.
Error Message / Title | Cause | How 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 externalId | The 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 required | You 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 valid | The 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 low | Your 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 invalid | The 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 invalid | The 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 / Title | Cause | Solution |
---|---|---|
Travel rule validation failed | One 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 TR | Add the missing required fields listed to ensure your payload is complete. |
Binance Identity Validation
Error Message / Title | Cause | Solution |
---|---|---|
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 found | This 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 toapplication/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