> ## Documentation Index
> Fetch the complete documentation index at: https://terminal-docs.xendit.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors & Simulations

> Error handling and testing simulations for the Terminal API

# 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.

<ResponseField name="error_code" type="string">
  Error code
</ResponseField>

<ResponseField name="message" type="string">
  Error message
</ResponseField>

## Error Codes

### Validation Errors

<Card title="INVALID_REQUEST">
  **Missing or invalid parameters**

  <Info>
    Occurs when required fields are missing or contain invalid data types or formats.
  </Info>

  ```json theme={null}
  {
    "error_code": "INVALID_REQUEST",
    "message": "Missing required parameter: terminal_id"
  }
  ```

  <Steps>
    <Step title="Check Parameters">
      Verify all required parameters are present and correctly formatted
    </Step>

    <Step title="Validate Data Types">
      Ensure data types match the API specification
    </Step>

    <Step title="Retry with Corrected Data">
      Fix the request and retry
    </Step>
  </Steps>
</Card>

<Card title="DUPLICATED_REQUEST">
  **Duplicated reference id**

  <Info>
    Occurs when the same idempotency key is used for multiple requests.
  </Info>

  ```json theme={null}
  {
    "error_code": "DUPLICATED_REQUEST",
    "message": "Request with same idempotency key already exists"
  }
  ```

  <Steps>
    <Step title="Check Idempotency Key">
      Ensure the idempotency key is unique across all environments
    </Step>

    <Step title="Generate New Key">
      Create a new unique idempotency key
    </Step>

    <Step title="Retry Request">
      Retry with the new idempotency key
    </Step>
  </Steps>
</Card>

### Authentication Errors

<Card title="UNAUTHORIZED">
  **Unauthorized, invalid API Key**

  <Info>
    Occurs when the API key is missing, invalid, or lacks necessary permissions.
  </Info>

  ```json theme={null}
  {
    "error_code": "UNAUTHORIZED",
    "message": "Invalid API key or insufficient permissions"
  }
  ```

  <Steps>
    <Step title="Verify API Key">
      Check that the API key is correct and active
    </Step>

    <Step title="Check Encoding">
      Ensure the API key is properly base64 encoded with the colon
    </Step>

    <Step title="Contact Support">
      If the issue persists, contact Xendit support
    </Step>
  </Steps>
</Card>

### Terminal & Configuration Errors

<Card title="TERMINAL_NOT_FOUND">
  **The terminal id is not configured for your account**

  <Info>
    Occurs when the specified terminal ID is not registered or configured for your account.
  </Info>

  ```json theme={null}
  {
    "error_code": "TERMINAL_NOT_FOUND",
    "message": "Terminal with ID 'TERM123' not found or not configured"
  }
  ```

  <Steps>
    <Step title="Verify Terminal ID">
      Double-check the terminal ID matches exactly
    </Step>

    <Step title="Check Registration Status">
      Contact support to verify registration is complete
    </Step>

    <Step title="Confirm Environment">
      Ensure using test API key with test terminal registration
    </Step>
  </Steps>
</Card>

<Card title="COMMAND_NOT_SUPPORTED">
  **The command currently not supported for this terminal**

  <Info>
    Occurs when attempting to use a feature or command not available on the specified terminal.
  </Info>

  ```json theme={null}
  {
    "error_code": "COMMAND_NOT_SUPPORTED",
    "message": "QR code payments not supported on this terminal model"
  }
  ```

  <Steps>
    <Step title="Check Terminal Capabilities">
      Verify the terminal supports the requested command
    </Step>

    <Step title="Use Alternative Terminal">
      Try a different terminal that supports the feature
    </Step>

    <Step title="Contact Support">
      Ask about terminal upgrade options if needed
    </Step>
  </Steps>
</Card>

### Business Logic Errors

<Card title="CURRENCY_NOT_SUPPORTED">
  **Currency is not supported for your account**

  <Info>
    Occurs when attempting to process a payment in a currency not enabled for your account.
  </Info>

  ```json theme={null}
  {
    "error_code": "CURRENCY_NOT_SUPPORTED",
    "message": "Currency 'JPY' is not supported for your account"
  }
  ```

  <Steps>
    <Step title="Check Supported Currencies">
      Verify which currencies are enabled for your account
    </Step>

    <Step title="Contact Support">
      Request currency activation from Xendit support
    </Step>

    <Step title="Use Supported Currency">
      Retry with a supported currency
    </Step>
  </Steps>
</Card>

## Error Handling Best Practices

<CardGroup cols={2}>
  <Card title="Parse Error Response" icon="code">
    Always parse the error response and use the error code or message to determine the cause of the failure
  </Card>

  <Card title="Log Errors" icon="file-text">
    Log error responses for debugging and monitoring purposes
  </Card>

  <Card title="Retry Logic" icon="refresh">
    Implement appropriate retry logic for transient errors
  </Card>

  <Card title="User Feedback" icon="user">
    Provide meaningful error messages to end users when appropriate
  </Card>
</CardGroup>

## Example Error Response

```json theme={null}
{
  "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.

<Info>
  **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.
</Info>

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.

<Warning>
  These simulations only work in test mode. In production mode, all transactions will be processed normally.
</Warning>

### Payment Session Simulations

| Case                | Amount (6 digits) | Terminal ID | Description                                      | Expected Behavior                   |
| ------------------- | ----------------- | ----------- | ------------------------------------------------ | ----------------------------------- |
| Failed to Pay       | `400508`          | All         | Emulates: Payment declined by terminal           | Session created, transaction failed |
| Channel Unavailable | `400509`          | All         | Emulates: Channel is not available by any reason | Session failed to create            |
| Canceled            | `400711`          | All         | Emulates: User canceled on terminal              | Session created, then canceled      |
| Invalid TID         | Any               | `4040404`   | Invalid terminal ID                              | Session 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](/guides/getting-started/quickstart#physical-terminal-testing) in our quickstart guide.

#### Key Differences: Real Terminal Testing vs Simulation

<Tabs>
  <Tab title="Real Terminal Testing">
    **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
  </Tab>

  <Tab title="Simulation Testing">
    **API-only testing without hardware**

    * **✓** Immediate testing without hardware
    * **✓** Comprehensive error scenario testing
    * **✓** Webhook integration validation
    * **✓** No registration required
    * **✓** Faster development cycles
    * **×** No physical hardware validation
    * **×** Limited to API-level testing
  </Tab>
</Tabs>

#### Troubleshooting Real Terminal Testing

<Tip>
  For runtime recovery scenarios such as timeouts, missing responses, and receipt-handling flows across H2H and C2C, see the [SDK Troubleshooting Guide](/sdk/troubleshooting).
</Tip>

<AccordionGroup>
  <Accordion title="Terminal Not Responding">
    **Symptoms**: API calls succeed but terminal doesn't show payment prompts

    <Steps>
      <Step title="Check Terminal Status">
        Verify terminal shows "Connected" in Terminal Gateway
      </Step>

      <Step title="Verify Registration">
        Confirm terminal ID is registered for test mode
      </Step>

      <Step title="Test Network Connection">
        Ensure terminal has stable network connectivity
      </Step>

      <Step title="Restart Terminal Gateway">
        Restart the Terminal Gateway app/SDK connection
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="TERMINAL_NOT_FOUND Error">
    **Symptoms**: API returns error code `TERMINAL_NOT_FOUND`

    <Steps>
      <Step title="Verify Terminal ID">
        Double-check the terminal ID matches exactly
      </Step>

      <Step title="Check Registration Status">
        Contact support to verify registration is complete
      </Step>

      <Step title="Confirm Environment">
        Ensure using test API key with test terminal registration
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Transactions Fall Back to Simulation">
    **Symptoms**: API works but no physical terminal interaction

    <Steps>
      <Step title="Confirm Registration">
        Verify terminal is registered (unregistered terminals auto-simulate)
      </Step>

      <Step title="Check Terminal Gateway Mode">
        Ensure Terminal Gateway is in test mode, not simulation mode
      </Step>

      <Step title="Validate Terminal Connection">
        Confirm terminal shows active connection status
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

<Note>
  **Best Practice**: Start with simulation testing for initial integration, then move to real terminal testing for final validation before production.
</Note>

## Testing

For comprehensive testing instructions, including both simulation and physical terminal testing, see our [quickstart guide](/guides/getting-started/quickstart#for-physical-terminal-testing).