> ## Documentation Index > Fetch the complete documentation index at: https://developers.orchestrasolutions.com/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Diagnose and resolve common integration issues with Orchestra. Common issues and how to resolve them. If your problem is not covered here, check the [Support](/support) page. ## Authentication Errors ### 401 Unauthorized **Symptom:** API returns `401` with "Bad or missing authorization data." **What to check:** 1. Verify the `Authorization` header uses the `APIKEY` prefix: `Authorization: APIKEY your-key-here` 2. Confirm the API key is active. Use the [Validate API Key](/guides/rest-api/utilities/validate-api-key) endpoint to test. 3. Check whether you are using a test key against the production environment (or vice versa). ### 409 Conflict on credential operations **Symptom:** Storing or updating a Payment Gateway Account returns `409`. **What to check:** 1. The `paymentGatewayAccountName` may already exist. List your accounts with [List Payment Gateway Accounts](/api-reference/paymentgatewayaccounts/list-payment-gateway-accounts) to confirm. 2. If you intend to replace existing credentials, the PUT endpoint overwrites by design. Ensure you are sending the full credential set. ## Transaction Failures ### Transaction returns "Rejected" **Symptom:** A charge or authorization returns a `Rejected` status. **What to check:** 1. Read the `GatewayDescription` and `AcquirerDescription` fields in the response. These contain the gateway's reason for the rejection (e.g., insufficient funds, invalid card, do-not-honor). 2. If using test cards, confirm you are using the [mock PSPs](/guides/utilities/mock-psps) or the gateway's own sandbox credentials. 3. Check [Gateway-Specific Requirements](/guides/rest-api/gateway-requirements) for the gateway you are using. Some gateways require specific parameters (e.g., AMEX requires `myRef` with 6+ characters). ### Transaction times out **Symptom:** The API call takes too long and times out, or returns a timeout error. **What to do:** 1. Do **not** retry the charge immediately. The original transaction may still be processing at the gateway. 2. Use the [Transaction Status](/guides/rest-api/transaction-status) endpoint with the `transactionId` from your original request to check the outcome. 3. Only retry after confirming the original transaction failed. See the [timeout handling pattern](/guides/rest-api/transaction-status#timeout-handling) for a complete code example. ### Gateway returns "FatalFailure" **Symptom:** Transaction returns `FatalFailure` status. **What to check:** 1. This typically means the gateway configuration is wrong (invalid credentials, disabled account, unsupported operation). 2. Verify your gateway credentials are correct using [List Payment Gateway Accounts](/api-reference/paymentgatewayaccounts/list-payment-gateway-accounts). 3. Confirm the gateway supports the operation you are attempting. For example, AMEX does not support direct Charge or Refund operations (use PreAuth + Capture instead). 4. If using [multi-gateway failover](/guides/rest-api/multi-gateway-failover), Orchestra automatically tries the next gateway in your list. ## Gateway-Specific Issues ### AMEX: "Bad Data" on charge AMEX requires the `myRef` parameter with at least 6 characters. Only the first 6 characters are used as the trace number. ### Pesopay: duplicate transaction error Pesopay requires `myRef` to be unique per transaction. Reusing a reference value causes a rejection. ### First Data / Gateline: connection refused These gateways require a client certificate for authentication. Verify that `paymentGatewayCertName` is set and the certificate is configured in your account. ### Adyen: unexpected test/live behavior The `ShopperInteraction` credential defaults to `Ecommerce`. For POS integrations, set this explicitly in your Payment Gateway Account credentials. For the full list of gateway-specific requirements, see [Gateway-Specific Requirements](/guides/rest-api/gateway-requirements). ## Card and Token Issues ### Invalid card number **Symptom:** Tokenization fails with a card validation error. **What to check:** 1. The card number must pass the [Luhn algorithm](https://en.wikipedia.org/wiki/Luhn_algorithm). Use the [Luhn Validation](/guides/rest-api/utilities/card-tools/luhn-validation) tool to verify. 2. Card number must be 12-19 digits with no spaces or separators. 3. Use the [Brand Lookup](/guides/rest-api/utilities/card-tools/brand-lookup) tool to confirm the card brand is supported by your gateway. ### Token not found **Symptom:** A string token operation returns `404`. **What to check:** 1. String tokens are deleted after retrieval by default. If you need to retrieve a token multiple times, store it with the appropriate retention setting. 2. Confirm the token ID is correct and belongs to the authenticated API key. ## Payments Library Issues ### Session token invalid **Symptom:** Library operations fail with "Session token is invalid." **What to check:** 1. Session tokens are single-use. A new session must be created for each payment attempt. 2. Ensure the `Authorization: Bearer ` header is set correctly in library API calls. 3. Verify the session was created with the correct `mode` (`LIVE` vs `TEST`). Sandbox accounts cannot create `LIVE` sessions. ### 3D Secure not triggering **What to check:** 1. Mock PSPs do not support 3D Secure. You must use a real gateway's sandbox credentials for 3DS testing. 2. Ensure your gateway account has 3DS enabled on the gateway's side. 3. The Payments Library handles 3DS automatically when the gateway requires it. If you are using the REST API directly, see the [3D Secure guide](/guides/rest-api/3d-secure). ## Debugging Tips ### Include `myRef` in every request Set a unique `myRef` value on every transaction. This makes it easy to trace transactions in gateway dashboards and when contacting support. ### Check the response body Orchestra returns the gateway's own response in `GatewayDescription` and `AcquirerDescription`. These fields contain the most specific error information and are the first place to look when a transaction fails. ### Test with mock PSPs first The [mock PSPs](/guides/utilities/mock-psps) let you test your integration without external gateway accounts. They support Charge, PreAuth, Capture, Refund, and Void operations with predictable responses. Mock PSPs do not support 3D Secure, gateway tokenization, or real card validation. Graduate to a real gateway sandbox for testing these features. ### Contact support with context When reaching out to [support](/support), include: * Your `myRef` value and `transactionId` * The full API response (including `GatewayDescription`) * The gateway name and operation type * Whether you are using test or production credentials ## Related * [Return Codes](/api-reference/overview#common-response-codes) - Full list of Orchestra error codes * [Gateway-Specific Requirements](/guides/rest-api/gateway-requirements) - Per-gateway parameter rules * [Transaction Status](/guides/rest-api/transaction-status) - Check the outcome of a transaction * [Mock PSPs](/guides/utilities/mock-psps) - Test without external accounts