Troubleshooting

Request debugging

Every API response includes a request_id: in error responses inside error.request_id, and as an X-Request-Id header on all responses. Quote this when contacting support.

{
  "error": {
    "code": "VALIDATION",
    "message": "amount_minor must be a positive integer.",
    "request_id": "OUI-REQ-01M2S18..."
  }
}

Common issues

"UNAUTHENTICATED" on every request

• Confirm the Authorization header is Bearer sk_test_... (with a space after Bearer).
• Confirm the key is not revoked: check Dashboard > Developers > API keys.
• Confirm you are using the correct environment key: sk_test_ for sandbox, sk_live_ for production.

"VALIDATION" errors

• Confirm Content-Type: application/json is set on all requests with a body.
• Confirm amount_minor is a positive integer (not a float, not a string).
• Confirm currency is a valid ISO 4217 code.
• Confirm phone is in E.164 format (e.g. +2348012345678).

"IDEMPOTENCY_REPLAY" (409)

You re-sent a request with the same Idempotency-Key but a different payload. On retry, the key and the body must be identical. If you need a different operation, use a new key.

"METHOD_NOT_SELECTABLE" (422)

The payment method is not enabled for this customer's country, KYC level, or provider coverage. Call GET /v1/payments/methods?customer_id=... to see which methods are selectable.

"RATE_LIMITED" (429)

You have exceeded the rate limit. Check X-RateLimit-Remaining and X-RateLimit-Reset headers. Back off and retry. Default limits:

Transaction stuck in "pending"

A pending transaction has not yet been submitted to the provider. If it stays pending for more than expected, check the status page for platform maintenance.

Transaction in "unknown"

The provider did not confirm or deny the outcome (typically a timeout). Do not retry. Wait for the webhook or requery the transaction. Reconciliation resolves it to completed or failed.

Webhook not arriving

• Confirm your endpoint returns 2xx within 10 seconds.
• Confirm your endpoint is reachable from the internet (not localhost).
• Check consecutive_failures on the subscription: it may be auto-disabled.
• Check the delivery log in Dashboard > Webhooks > Deliveries.

Getting support

When contacting support, include:

• The request_id from the error response
• The full error response body
• The timestamp of the request
• Your account email