Error Handling

When an API request fails, do not guess. Check it in this order:

1. Check the HTTP status. 401 means authentication, 403 means permission, and 400 usually means request data.
2. Check message. It tells you which field or configuration caused the problem.
3. Use the tables below to fix the request or account configuration.

Success response:

{
  "code": 0,
  "message": "ok",
  "data": {}
}

Error response:

{
  "code": 53,
  "message": "payout route not configured",
  "data": null
}

Quick Check

HTTP Status	Meaning	Check First
400	Request data or business configuration is wrong	fields, amount, currency, recipient, payout route
401	Authentication failed	API key, Bearer token, IP whitelist
403	Authenticated but not allowed	API key permission, product access
404	Resource does not exist or is not visible	payout_id, order_id, batch_id, environment
500	Platform or upstream error	query current status before retrying

Response Fields

Field	Meaning
code	Business result code. 0 means success.
message	Main troubleshooting hint. The list below is organized by this field.
data	Success payload. Usually empty on errors.

Common codes:

code	Meaning
0	Success
51	Basic validation failed, such as missing required fields or invalid length
53	Business parameter or business configuration is wrong
61	Authentication or permission failed
65	Resource not found
50	Platform or upstream error

Authentication And Permission

message	Meaning	What To Do
unauthorized	Token is missing, malformed, or invalid	Send Authorization: Bearer <token> or X-API-Key: <token>
api key not found	API key does not exist, or Sandbox / Live environment is wrong	Create a new API key and verify the environment
api key disabled	API key is disabled	Enable it or create a new one
api key expired	API key expired	Create or renew the API key
api key version mismatch	API key was rotated and the old token is invalid	Use the latest token
invalid api key token	Token content is incomplete or malformed	Copy the full token again
ip not allowed	Server egress IP is not whitelisted	Add your server egress IP to the API key whitelist
ip not allowed: <ip>	<ip> is the source IP seen by Beyounger	Add that IP to the whitelist
forbidden	API key lacks permission or product access is not enabled	Grant permission or enable the product

Common permissions:

Action	Permission
Read account	payment.account.read
Read balances	payment.wallet.read
Read ledger	payment.ledger.read
Create Quick Payout / payout	payment.payout.create
Read payouts	payment.payout.read
Update payout	payment.payout.update
Submit payout	payment.payout.submit
Cancel payout	payment.payout.cancel
Manage beneficiaries	payment.payout.beneficiary.read / payment.payout.beneficiary.write
Manage beneficiary accounts	payment.payout.beneficiary_account.read / payment.payout.beneficiary_account.write

Common Request Errors

message	Meaning	What To Do
Validation Failed	A required field, length, enum, or minimum rule failed	Fix the field according to the API reference
request required	Request body is empty or JSON was not parsed	Send valid JSON with Content-Type: application/json
<field> required	A required field is missing	Add the field shown in the message
invalid notify_url	Callback URL is invalid	Use a full URL, such as https://merchant.example.com/webhooks/payout
invalid status	Unsupported status filter	Use documented status values
invalid review_status	Unsupported review status	Use draft, pending_review, returned, rejected, or approved
invalid execution_status	Unsupported execution status	Use init, processing, completed, failed, or cancelled
no changes	Update request has no changed fields	Send at least one field to update
account not found	API key account does not exist or environment is wrong	Check API key and environment
account frozen	Merchant account is frozen	Contact Beyounger
internal error	Internal details are hidden	Keep request time, path, payload, and response for support

Fiat Payout

message	Meaning	What To Do
currency required	Payout currency is missing	Send currency, such as USD
currency not supported	Account does not support the currency	Confirm the currency is enabled
amount must be greater than zero	Amount must be positive	Send an amount greater than 0
amount must be greater than fee when fee_bearer is user	Amount is not enough after user-borne fee	Increase amount or use fee_bearer: merchant
fee_bearer must be merchant or user	Fee bearer value is invalid	Use merchant or user
reference required	Merchant reference is missing	Send a unique reference
reference already exists	The same reference was already used	Query the original payout before creating another one
beneficiary_account_id required	No existing account or inline recipient was sent	Send beneficiary_account_id, or send both beneficiary and beneficiary_account
beneficiary and beneficiary_account must be provided together	Only one inline object was sent	Send both objects
method_id required when creating beneficiary inline	Inline beneficiary creation needs a method	Send method_id
channel_id requires method_id	channel_id was sent without method_id	Send the matching method_id
method_id required when channel_id provided	channel_id was sent without method_id	Send the matching method_id
payout method not found	Method does not exist or is not enabled for the merchant	Verify method_id or ask Beyounger to enable it
payout channel not found	Channel does not exist or is not configured	Do not send channel_id unless Beyounger provides it
payout route not configured	No route matches account, currency, method, and amount	Ask Beyounger to configure payout routing
channel account not configured	Route exists but channel account is missing	Ask Beyounger to configure the channel account
payout method not supported for currency type	Fiat / crypto method type is mixed	Use a fiat method for fiat payout
beneficiary account not found	Beneficiary account does not exist or is out of scope	Check beneficiary_account_id
beneficiary account not active	Beneficiary account is not active	Enable or recreate it
beneficiary account disabled, please enable it first	Beneficiary account is disabled	Enable it first
beneficiary account suspended	Beneficiary account is suspended	Contact Beyounger or use another account
beneficiary account type mismatch	Account type does not match currency or route	Do not send account_type unless provided by Beyounger
account_type mismatch	Sent account_type does not match route rules	For PayPal, usually omit account_type: paypal
beneficiary not found	Beneficiary does not exist or is out of scope	Check beneficiary_id
beneficiary disabled	Beneficiary is disabled	Enable or recreate it
beneficiary method mismatch	Beneficiary method conflicts with request method_id	Use a matching method_id or recreate beneficiary
beneficiary channel mismatch	Beneficiary channel conflicts with request channel_id	Use matching channel or omit channel_id
beneficiary account mismatch	Beneficiary and beneficiary account do not belong together	Use an account under the same beneficiary
beneficiary profile incomplete: missing <fields>	Provider requires more recipient profile fields	Fill all fields listed in <fields>
wallet not found	Account has no wallet for the currency	Ask Beyounger to enable the wallet
merchant account not found	Account setup is incomplete	Ask Beyounger to check account setup
payout not found	Payout does not exist or is not visible	Check payout_id and environment
payout not editable	Payout can no longer be edited	Query status before updating
payout already approved	Payout was already approved	Wait for execution result or query status
payout already processing	Payout is being executed	Wait for webhook or query status
payout rejected	Payout was rejected	Fix data and create a new payout
invalid payout status	Current status does not allow the operation	Query payout status first

Beneficiary Fields

These errors usually come from beneficiary.fields.

message	Meaning	What To Do
beneficiary fields required	Beneficiary fields are missing	Send beneficiary.fields
fields required	Field object is missing	Send fields
fields missing required: <fields>	Required fields are missing	Fill the fields listed in <fields>
fields.payee_id invalid: expect ^[a-zA-Z0-9]{3,60}$	payee_id must be 3-60 alphanumeric characters	Fix the ID
fields.language invalid: expect 2 letters	Language must be 2 letters	Use values like en
fields.country invalid: expect ISO-2 uppercase	Country must be uppercase ISO-2	Use values like US
fields.phone invalid: expect (\\+[0-9]{1,3}-)?[0-9]{4,12}	Phone format is invalid	Use +1-4155550100 or 4-12 digits
fields.birthdate invalid: expect yyyy-MM-dd	Birthdate format is invalid	Use 1990-01-31
fields.email invalid	Email format is invalid	Send a valid email
fields.first_name invalid: length 3-100, letters/'/-/space only	First name format is invalid	Use 3-100 letters, spaces, ', or -
fields.last_name invalid: length 3-100, letters/'/-/space only	Last name format is invalid	Use 3-100 letters, spaces, ', or -
fields.zip invalid: length 3-30	ZIP/postal code length is invalid	Use the recipient country format
fields.zip invalid for country <country>	ZIP/postal code does not match the country	Fix it for <country>
fields.city invalid: length 2-120	City length is invalid	Use 2-120 characters
fields.state invalid: length 2-60	State length is invalid	Use 2-60 characters
fields.address invalid: length 3-200	Address length is invalid	Use 3-200 characters

Beneficiary Account Fields

These errors usually come from beneficiary_account or beneficiary account APIs.

message	Meaning	What To Do
network_code required	Receiving network is missing	Send beneficiary_account.network_code
network not found	Network is not available	Query GET /payment/payout-networks first
schema required	Network field schema is missing	Contact Beyounger
field <name> required	Account field is missing	Fill it according to network schema
field <name> invalid	Account field format is invalid	Follow the schema hint
field <name> invalid: <hint>	Account field format is invalid	Fix it according to <hint>
unknown field <name>	Field is not defined by schema	Remove the field
cashapp_account must start with $	Cash App account must start with $	Use a value like $example
beneficiary account already exists	Same beneficiary account already exists	Reuse the existing account

Crypto Mass Payout

message	Meaning	What To Do
items required	Batch items are missing	Send items
items length must be between 1 and 500	Batch must contain 1-500 items	Split the batch or add items
only crypto currency supported	Fiat currency was used	Use a crypto currency
method_id required	Payout method is missing	Send a crypto method_id
payout method not supported for crypto	Method is not a crypto payout method	Use a crypto method
order_no required	Item order number is missing	Send unique order_no for each item
duplicate order_no in request	Duplicate order number in current request	Deduplicate
duplicate order_no in batch	Duplicate order number in batch	Use a new order_no
duplicate order_no in merchant payouts	Order number was used before	Query the original payout
beneficiary_account.address required	Receiving address is missing	Send address
receiving address required	Receiving address is missing	Send address
invalid EVM receiving address	EVM address is invalid	Use a valid EVM address
invalid TRON receiving address	TRON address is invalid	Use a valid TRON address
duplicate receiving address in batch request	Duplicate address in batch	Deduplicate or split the batch
batch not found	Batch does not exist or is not visible	Check batch_id and environment
batch not editable	Batch can no longer be edited	Query batch status
batch not ready for submit	Batch cannot be submitted yet	Fix batch items first
batch has no items	Batch has no items	Add items
batch not approved	Batch is not approved	Wait for review result
batch contains multiple payout channel accounts; split batch by route	Batch uses multiple payout routes	Split the batch by route

Acquiring

message	Meaning	What To Do
order_currency only supports USD	Order currency must be USD	Send USD
order_amount must be > 0	Order amount must be positive	Send an amount greater than 0
expire_seconds must be between 60 and 10800	Expiration is outside the allowed range	Use 60-10800 seconds
underpay_tolerance must be >= 0	Underpay tolerance cannot be negative	Send 0 or a positive value
allowed_pay_currencies required	Allowed pay currencies are missing	Send allowed_pay_currencies
notify_webhook_id required	Acquiring webhook ID is missing	Send a valid notify_webhook_id
notify_webhook_id invalid or inactive	Webhook is missing or inactive	Enable webhook in merchant dashboard
notify_webhook_id not subscribed to acquiring events	Webhook is not subscribed to acquiring events	Subscribe it to acquiring.*
redirect_url must be an absolute https URL or a same-origin relative path	Redirect URL format is invalid	Use HTTPS full URL or same-origin relative path
logo_url must be an absolute https URL	Logo URL must be HTTPS full URL	Use HTTPS image URL
mode must be checkout or direct	Acquiring mode is invalid	Use checkout or direct
unsupported checkout_type	Checkout type is not supported	Use an enabled checkout type
network/currency required	Network and currency must be sent together	Send both network and currency
network/currency not allowed by order	Payment option is not allowed by the order	Use an allowed option
unsupported network/currency: <network>/<currency>	Account does not support that network/currency pair	Use another option or ask Beyounger to enable it
no available pay tokens for current account	Account has no enabled pay tokens	Ask Beyounger to configure pay tokens
order not found	Order does not exist or is not visible	Check order_id and environment
completed order cannot be closed	Completed order cannot be closed	Treat it as completed
checkout_url not found	Hosted checkout URL is not available	Check order ID and order mode

Webhook Receiving

These errors usually happen when Beyounger receives callbacks from upstream providers. Merchants usually only need to keep logs and contact Beyounger if needed.

message	Meaning	What To Do
webhook ip not allowed	Callback source IP is not allowed	Check upstream IP whitelist configuration
unsupported acquiring webhook provider: <provider>	Webhook provider is not supported	Check provider configuration
empty cobo webhook event	Cobo webhook event is empty	Save the raw callback
invalid cobo merchant deposit payload	Cobo payload format is invalid	Save the raw payload
acquiring order not found	Callback cannot match a local acquiring order	Check upstream order reference
merchant deposit address not found	Callback address cannot match merchant deposit address	Check deposit address setup

Retry Rules

Error Type	Retry Directly?	Guidance
401 / 403	No	Fix token, IP whitelist, or permission first
400 request error	No	Fix request fields first
404 not found	No	Check ID, account, and environment first
Query API 5xx	Yes	Retry with backoff
Create / submit / payout API 5xx	Carefully	Query by reference, client_request_id, or payout_id before retrying