Code table
| Code | Meaning | Why you got it | What to do |
|---|---|---|---|
| 200 | OK | Success | Parse the response. For flows that return a payment link, pick up linktopay_url. For token charges, check the status field. |
| 208 | Already reported | Duplicate reference ID | Your reference_number has been used before. Either fetch the prior transaction, or regenerate a unique reference. |
| 400 | Bad request | Missing or invalid parameter | Response body names the offending field. Check the field reference and resend. |
| 401 | Unauthorized | Invalid API key — wrong key, rotated key, or IP not whitelisted | Confirm X-API-KEY matches the value issued for this environment. If the key is IP-restricted, confirm the source IP is in the allowed list. |
| 405 | Method not allowed | Wrong HTTP verb for this endpoint | Payment Service API expects POST multipart/form-data. URL POST API expects GET with query parameters. |
| 500 | Internal server error | Server-side failure — database or downstream gateway error | Retry with exponential backoff. If it persists, contact support with the request ID from the response. |
| 502 | Bad gateway | Upstream payment gateway didn't respond cleanly | Transient. Retry with backoff; if stuck, check the status page at status.paytia.com. |
| 503 | Service unavailable | Paytia or a gateway is temporarily down | Retry with backoff. Short outages are usually deploys or gateway-side; status page has the detail. |
| 504 | Gateway timeout | Upstream gateway didn't respond in time | Retry. Don't double-charge — use an idempotent reference_number so repeats don't create duplicate transactions. |
Retry strategy
For transient 5xx errors (502, 503, 504), retry with exponential backoff — 1s, then 2s, then 4s, capped at around 30s. Use the same reference_number on retries so Paytia and the downstream gateway can deduplicate. 4xx errors should not be retried — fix the request.
Finding the request ID
Every response carries an opaque request ID in the X-Paytia-Request-Id header. Include it in any support ticket — it lets us trace the request end to end through our logs.