Skip to main content

​
Errors & Simulations

Error handling is an essential part of integrating with the Xendit’s Payment Terminal API. This section covers error codes, error handling best practices, and testing simulations.

​
Error Data Structure

An error occurs when the HTTP status is not 200.
​
error_code
string
Error code
​
message
string
Error message

​
Error Codes

​
Validation Errors

INVALID_REQUEST

Missing or invalid parameters
Occurs when required fields are missing or contain invalid data types or formats.
{
  "error_code": "INVALID_REQUEST",
  "message": "Missing required parameter: terminal_id"
}
1

Check Parameters

Verify all required parameters are present and correctly formatted
2

Validate Data Types

Ensure data types match the API specification
3

Retry with Corrected Data

Fix the request and retry

DUPLICATED_REQUEST

Duplicated reference id
Occurs when the same idempotency key is used for multiple requests.
{
  "error_code": "DUPLICATED_REQUEST",
  "message": "Request with same idempotency key already exists"
}
1

Check Idempotency Key

Ensure the idempotency key is unique across all environments
2

Generate New Key

Create a new unique idempotency key
3

Retry Request

Retry with the new idempotency key

​
Authentication Errors

UNAUTHORIZED

Unauthorized, invalid API Key
Occurs when the API key is missing, invalid, or lacks necessary permissions.
{
  "error_code": "UNAUTHORIZED",
  "message": "Invalid API key or insufficient permissions"
}
1

Verify API Key

Check that the API key is correct and active
2

Check Encoding

Ensure the API key is properly base64 encoded with the colon
3

Contact Support

If the issue persists, contact Xendit support

​
Terminal & Configuration Errors

TERMINAL_NOT_FOUND

The terminal id is not configured for your account
Occurs when the specified terminal ID is not registered or configured for your account.
{
  "error_code": "TERMINAL_NOT_FOUND",
  "message": "Terminal with ID 'TERM123' not found or not configured"
}
1

Verify Terminal ID

Double-check the terminal ID matches exactly
2

Check Registration Status

Contact support to verify registration is complete
3

Confirm Environment

Ensure using test API key with test terminal registration

COMMAND_NOT_SUPPORTED

The command currently not supported for this terminal
Occurs when attempting to use a feature or command not available on the specified terminal.
{
  "error_code": "COMMAND_NOT_SUPPORTED",
  "message": "QR code payments not supported on this terminal model"
}
1

Check Terminal Capabilities

Verify the terminal supports the requested command
2

Use Alternative Terminal

Try a different terminal that supports the feature
3

Contact Support

Ask about terminal upgrade options if needed

​
Business Logic Errors

CURRENCY_NOT_SUPPORTED

Currency is not supported for your account
Occurs when attempting to process a payment in a currency not enabled for your account.
{
  "error_code": "CURRENCY_NOT_SUPPORTED",
  "message": "Currency 'JPY' is not supported for your account"
}
1

Check Supported Currencies

Verify which currencies are enabled for your account
2

Contact Support

Request currency activation from Xendit support
3

Use Supported Currency

Retry with a supported currency

​
Error Handling Best Practices

Parse Error Response

Always parse the error response and use the error code or message to determine the cause of the failure

Log Errors

Log error responses for debugging and monitoring purposes

Retry Logic

Implement appropriate retry logic for transient errors

User Feedback

Provide meaningful error messages to end users when appropriate

​
Example Error Response

{
  "error_code": "INVALID_REQUEST",
  "message": "Missing required parameter: terminal_id"
}

​
Simulations

Perfect for merchants without physical terminals yet! You can start integrating immediately using our simulation capabilities. No need to wait for terminal delivery - test payment flows, error handling, and webhook integrations using special test amounts and terminal IDs.
Getting Started Without Hardware: Use any terminal_id value (like SIM001) and special test amounts to simulate different payment scenarios. This is ideal for merchants waiting on terminal delivery or those who want to build and test their integration before hardware arrives.
For testing purposes in test mode, the following special amounts and terminal IDs can be used to trigger specific situations or errors. Otherwise the API will always succeed.
These simulations only work in test mode. In production mode, all transactions will be processed normally.

​
Payment Session Simulations

CaseAmount (6 digits)Terminal IDDescriptionExpected Behavior
Failed to Pay400508AllEmulates: Payment declined by terminalSession created, transaction failed
Channel Unavailable400509AllEmulates: Channel is not available by any reasonSession failed to create
Canceled400711AllEmulates: User canceled on terminalSession created, then canceled
Invalid TIDAny4040404Invalid terminal IDSession creation fails

​
Testing with Real Terminals in Test Mode

For detailed instructions on registering and testing with real terminals in test mode, see the Physical Terminal Testing section in our quickstart guide.

​
Key Differences: Real Terminal Testing vs Simulation

Uses physical hardware with test transactions
  • ✓ Real card reader interactions
  • ✓ Real money movement
  • ✓ Actual terminal display prompts
  • ✓ Physical button presses and card taps
  • ✓ Network connectivity testing
  • ✓ Complete hardware validation
  • ! Requires terminal registration
  • ! Dependent on physical hardware

​
Troubleshooting Real Terminal Testing

Symptoms: API calls succeed but terminal doesn’t show payment prompts
1

Check Terminal Status

Verify terminal shows “Connected” in Terminal Gateway
2

Verify Registration

Confirm terminal ID is registered for test mode
3

Test Network Connection

Ensure terminal has stable network connectivity
4

Restart Terminal Gateway

Restart the Terminal Gateway app/SDK connection
Symptoms: API returns error code TERMINAL_NOT_FOUND
1

Verify Terminal ID

Double-check the terminal ID matches exactly
2

Check Registration Status

Contact support to verify registration is complete
3

Confirm Environment

Ensure using test API key with test terminal registration
Symptoms: API works but no physical terminal interaction
1

Confirm Registration

Verify terminal is registered (unregistered terminals auto-simulate)
2

Check Terminal Gateway Mode

Ensure Terminal Gateway is in test mode, not simulation mode
3

Validate Terminal Connection

Confirm terminal shows active connection status
Best Practice: Start with simulation testing for initial integration, then move to real terminal testing for final validation before production.

​
Testing

For comprehensive testing instructions, including both simulation and physical terminal testing, see our quickstart guide.