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

StatusWhat it meansRetry?
200Success. On an order, this specific reference was already used.no
202The order was accepted and is on its way.no
400A path value was not usable, for example a non-numeric provider id.no
401No key, a malformed header, or a key that no longer exists.no
403The key is real but may not do this.no
404No order of yours carries that reference in this mode.no
422Refused: the request was not valid, or the order failed.only after fixing it
429Too many of your requests are in flight at once.yes, once some finish
500Something broke on our side.yes
502We could not reach something we needed.yes
503We 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

MessageCause
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:

  1. Retry with the same reference, or
  2. 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.