Debugging & Troubleshooting

This guide helps you diagnose and resolve common issues with your Gatelithix integration. Use correlation IDs, health endpoints, and structured error responses to quickly identify problems.

Request Correlation

Every API response includes an X-Request-Id header — a unique identifier for that request. This value is your primary debugging tool.

Key facts about X-Request-Id:

• Present in every response, including error responses.
• If you send an X-Request-Id header in your request, that value is used. Otherwise, the gateway generates a UUID v4 or uses the OpenTelemetry trace ID.
• The same value appears in the error response body as request_id.
• Always include the request ID in support tickets — it allows the team to trace the exact request through the system.

Health Endpoints

Use the health endpoints to check whether the Gatelithix API is operational.

Common Errors

| 401 | authentication_required | No Authorization header in the request. | Add Authorization: Bearer sk_test_your_key_here to every request. |

| 403 | insufficient_permissions | API key does not have the required role or scope. | Check the key’s assigned role in the dashboard. Some operations require admin-level keys. | | 404 | payment_intent_not_found | Payment ID does not exist or belongs to a different environment. | Verify the payment ID. Check that you are using the correct environment (test vs. live). | | 409 | invalid_state_transition | Payment is not in the correct status for this operation. | Check the payment status before the operation. For example, you can only capture a payment that is in authorized status. | | 409 | idempotency_conflict | Another request with this idempotency key is being processed. | Wait and retry — the original request is still in progress. | | 422 | idempotency_param_mismatch | Same idempotency key used with different request parameters. | Use a new unique idempotency key for requests with different parameters. | | 429 | rate_limit_exceeded | Too many requests in the current window. | Read the Retry-After header and wait. Implement exponential backoff. | | 502 | connector_error | The payment processor returned an error. | Check error.connector_code for the PSP-specific error. The card may need to be retried with a different processor. | | 504 | connector_timeout | The payment processor did not respond in time. | Retry with the same Idempotency-Key — this is safe due to idempotency guarantees. |

Debugging Payment Failures

Follow this step-by-step flow when a payment fails:

1. Check the error response.

{
  "error": {
    "type": "connector_error",
    "code": "connector_error",
    "message": "The card was declined.",
    "connector_code": "insufficient_funds",
    "request_id": "req_abc123def456"
  }
}

2. Identify the error category from error.type:

3. Note the request_id. Include it in any support ticket.

4. For connector errors, check connector_code. This gives you the PSP-specific reason (e.g., insufficient_funds, expired_card, do_not_honor).

5. For timeouts, retry safely. Use the same Idempotency-Key to retry. The gateway guarantees at-most-once processing per idempotency key.

6. If errors persist, check service health. Call GET /health/ready to verify the gateway and its dependencies are operational.

Idempotency Key Issues

Idempotency keys follow Stripe semantics. Common pitfalls:

Same key + different parameters = 422 error. This is by design. Each idempotency key is bound to the exact request parameters used in the first call. If you reuse a key with different parameters, the API returns a 422 idempotency_param_mismatch error.

Same key + same parameters = cached response. This is the intended retry behavior. If a request was already processed with this key, the original response is returned. This makes retries safe — you will never double-charge.

Best practices for idempotency keys:

• Use UUIDs (crypto.randomUUID() in JavaScript, uuid.uuid4() in Python).
• Generate a new key for each distinct request.
• Reuse the same key only when retrying the exact same request (e.g., after a timeout).
• Keys are scoped to your API key and expire after 24 hours.

Getting Help

When contacting support:

1. Include the X-Request-Id from the failed response. This is the fastest way to look up your request.
2. Include the full error response body. The type, code, and connector_code fields help diagnose the issue.
3. Include the timestamp of when the error occurred.
4. Check the dashboard  for payment history, webhook delivery status, and API key activity.

Next Steps

• Error Codes — Full error code reference.
• Rate Limiting — Understand and handle rate limits.
• Sandbox Testing — Test your error handling with decline cards.
• Webhooks — Monitor payment events in real time.