Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Response format, HTTP status codes and errors

Every endpoint answers with the same JSON envelope, success or failure.
{ "status": "success", "message": "Your Airtime Purchase To 08031234567 Was Successful... Thank You", "data": { } }
FieldTypeMeaning
status"success" or "failed"Whether the request did what you asked
messagestringHuman-readable result. Safe to log, not to parse for logic
dataobject, array or nullThe result. Shape depends on the endpoint; usually null on errors

Requests

  • GET endpoints take query parameters.
  • POST endpoints take a JSON body and require Content-Type: application/json. Form-encoded bodies fail with HTTP 500.
  • Amounts are in naira (not kobo).
Branch on the HTTP status, not the message. Messages are written for people and may be reworded.

HTTP status codes

HTTPMeaningTypical action
200Success, or accepted and queuedRead message; verify queued transactions
201Invoice already paid (collections)Treat as paid
206Transfer queued, not yet confirmedPoll Verify transfer
400Missing or invalid field, not enabled, not found, or still pendingFix the request, or check again later
401Provider gave no final answerDo not retry; verify the same tranx_id
404Record not foundCheck the reference you sent
406Unauthorized tokenFix or rotate your token
417Rejected or failed (and refunded when money moved)Show the reason; a new attempt needs a new tranx_id
500Unexpected server errorRetry later with the same tranx_id, then verify
503Product temporarily unavailable or under maintenanceRetry later

Validation errors

A missing field returns HTTP 400 naming the field:
{ "status": "failed", "message": "bad request (tranx_id) not found in request param", "data": null }
A value that is too short returns:
{ "status": "failed", "message": "(tranx_id) too short... please try again", "data": null }

Service maintenance

When a product is temporarily switched off (for example during a provider outage), its endpoints answer with HTTP 503 (some bill endpoints use 417) and nothing is charged:
{ "status": "failed", "message": "Service Unavailable... Please Try Again Shortly", "data": null }
During platform-wide maintenance the message is System Under Maintainance... Please Try Again Shortly. Retry later with the same tranx_id.