Errors
Each code has a status and a next step. Sandbox magic failures are included.
| Code | Status | When | Resolution |
|---|---|---|---|
IDEMPOTENCY_KEY_REQUIRED | 400 | A POST omitted Idempotency-Key. | Add Idempotency-Key: a uuid v4, then retry. |
PARTNER_MISMATCH | 403 | The key tenant and X-Tenant-Id disagree. | Send the tenant on the key, tn_sandbox_…, or omit the header. |
PARTNER_LIMIT_EXCEEDED | 400 | The call crosses the partner cap for this product and period. | Read headroom on /portal/usage. Wait for the period, or ask Ops to raise the cap. |
SCORE_NOT_FOUND | 404 | GET /v1/score has no row for that customerRef. | Check the ref. Do not retry the same unknown ref. |
KYC_SESSION_EXPIRED | 410 | The widget session is older than 15 minutes. | POST /v1/kyc/widget/session again and open the new URL. |
TOKEN_EXPIRED | 401 | The access token is older than one hour. | POST /auth/token again. There is no refresh token. |
KYB_REJECTED | 200 | Sandbox businessRef ends in 009. | This is a decision, not a transport error. Submit a new dossier, or use a businessRef that ends in 001 to see an approval. |
KYC_REJECTED | 200 | Sandbox phone +225000000009. | This is a decision, not a transport error. Submit a new dossier, or use +225000000001 in sandbox to see an approval. |
PAYMENT_FAILED | 200 | Sandbox amount ends in 00, for example 5000 XOF. | Retry with a new Idempotency-Key and an amount that ends in 77, for example 5077 XOF, to see a success. |
CREDIT_REJECTED | 200 | Sandbox amount ends in 99. | Simulate again with an amount of 100000 XOF or less that ends in 11. |