Errors
There are no error codes. Plan for that.
code in the envelope is the HTTP status, repeated. There is no second,
machine-readable identifier anywhere in this API. Five different 422s and
three different 403s are distinguishable only by their English message.
Warning
This is a real limitation and we would rather you hear it from us than find
it out. Branch on the HTTP status and on fields you can trust, such as an
order's state. If you must tell two refusals of the same status apart,
matching on message text is the only way, and message text is not a
stable contract: we may reword it. Treat such a match as a convenience, keep
it in one place in your code, and make sure the fallback path is safe.
Statuses
| Status | What it means | Retry? |
|---|---|---|
200 | Success. On an order, this specific reference was already used. | no |
202 | The order was accepted and is on its way. | no |
400 | A path value was not usable, for example a non-numeric provider id. | no |
401 | No key, a malformed header, or a key that no longer exists. | no |
403 | The key is real but may not do this. | no |
404 | No order of yours carries that reference in this mode. | no |
422 | Refused: the request was not valid, or the order failed. | only after fixing it |
429 | Too many of your requests are in flight at once. | yes, once some finish |
500 | Something broke on our side. | yes |
502 | We could not reach something we needed. | yes |
503 | We or a provider are briefly unavailable. | yes |
Important
When you retry an order, retry it with the same reference. A fresh reference on a retry is how a customer gets charged twice. See the reference, and retrying safely.
The three 403s
| Message | Cause |
|---|---|
This token cannot use the reseller API. | Not a partner key, or the account is not enabled or not KYB approved. |
This address is not on your allowlist. | Live keys only. Add the address, or call from one you allowlisted. |
This key carries both test and live access. Ask us to reissue it for one mode. | Contact us for a replacement key. |
Common 422s
These come from validation, before anything is charged:
reference is required. Use your own unique reference: retries with the same one will not vend twice.reference must be 120 characters or fewer.service must be electricity, airtime, data or cable_tv.meter_number is required.disco_code is required.amount must be greater than zero.access_code is required. Verify the meter with /api/v2/reseller/meters/verify and send the access_code it returns.provider_id is required. Read the providers for a service from /api/v2/reseller/catalogue/services/{service}/providers.target is required: the phone number or smartcard number being paid for.send amount for a service priced by amount, or plan_id for one sold as a plan.The request body is not valid JSON.
A 422 from the order path instead carries the order in data. That is a
failed order, not a rejected request, and the two need handling apart. See
the response envelope.
In test mode you will also meet:
This is not one of the sandbox test meters.Use one of the reserved meters.Your sandbox balance will not cover this order. Reset it from your dashboard to carry on testing.
429 is about concurrency, not rate
It means too many of your requests are open at the same time, not that you
have sent too many in the last minute. Backing off for a fixed period is the
wrong response. Let your open requests finish and send the next one then.
Retry-After is always 1. See Concurrency limits.
503 on an order needs care
Could not reach the provider. Try again shortly. means we do not know whether
the provider did anything. Your order may exist. Do not treat it as a failure:
- Retry with the same reference, or
- Call Get an order with that reference.
A 404 from that second call is the one thing that tells you nothing was
created and the reference is still free.