Guide

Errors & status codes

Every response in the Partner API adheres to a unified JSON envelope pattern, simplifying client-side error handling, pagination, and debugging.

Response envelopes

Successful single-resource responses:

Standard Success (200 / 201)

{
  "success": true,
  "message": "Airtime purchase initiated",
  "data": {
    "reference": "TXN_1720603200000_A1B2C3",
    "partnerReference": "PR-9182734",
    "status": "pending",
    "amount": 500,
    "totalCost": 485,
    "network": "mtn"
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/airtime/purchase"
}

Paginated collection responses (e.g. gift card products, transaction lists, KYC logs):

Paginated Success (200 OK)

{
  "success": true,
  "message": "Transactions retrieved",
  "data": [
    {
      "reference": "TXN_1720603200000_A1B2C3",
      "status": "success",
      "amount": 500,
      "type": "airtime"
    }
  ],
  "pagination": {
    "total": 142,
    "page": 1,
    "limit": 20,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/airtime/transactions"
}

Validation and business rule errors:

Validation Error (400 Bad Request)

{
  "success": false,
  "message": "Amount must not exceed 1000000",
  "error": "VALIDATION_ERROR",
  "details": null,
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/airtime/purchase"
}

Authentication and signature rejections:

Auth Error (401 Unauthorized)

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid signature"
  }
}

HTTP status codes

Status	Meaning
200	OK — Request succeeded (read queries, status lookups).
201	Created — Resource or transaction successfully created (registration, purchase, sell, beneficiary account).
400	Bad Request — Missing parameter, validation failed, or business logic violated.
401	Unauthorized — Missing/invalid `x-api-key`, bad signature, or timestamp skew > 5 mins.
403	Forbidden — Origin IP address is not whitelisted, or partner account is pending approval / suspended.
404	Not Found — Target resource, slug, or transaction reference was not found.
409	Conflict — Duplicate reference or conflicting resource state.
429	Too Many Requests — Route rate limit exceeded (30 req / 60s) or failure circuit breaker tripped.
500	Internal Server Error — Unexpected server error.
502	Bad Gateway — Downstream telecommunications/utility carrier error.
503	Service Unavailable — Provider maintenance or offline upstream gateway.

Machine-readable error codes

Code	HTTP Status	Description
VALIDATION_ERROR	400	Input payload failed schema validation. See `message` for specific field.
UNAUTHORIZED	401	Invalid credentials, bad HMAC signature, or expired timestamp.
AUTHORIZATION_ERROR	403	Origin IP address is not authorized for this API key, or partner account is suspended/pending.
NOT_FOUND	404	The requested product code, slug, or transaction does not exist.
INVALID_STATUS	403	Your partner account is not active.
INSUFFICIENT_BALANCE	400	Your main partner wallet does not have sufficient funds to cover the purchase.
TRANSACTION_FAILED	400	Transaction was declined by the carrier or provider.
DUPLICATE_TRANSACTION	409	A transaction with this `partnerReference` has already been executed.
RATE_LIMIT_EXCEEDED	429	Exceeded 30 requests per minute or triggered circuit breaker.
PROVIDER_ERROR	502 / 400	Upstream carrier network issue.
SERVICE_UNAVAILABLE	503	No active provider configured for the selected service type.
INTERNAL_ERROR	500	Internal server error. Safe to retry with exponential backoff.

Idempotent retries

Always provide a unique partnerReference on every write request. In case of network drops or client-side HTTP timeouts, retry using the same partnerReference. Our system detects the existing reference and returns the original transaction record without initiating duplicate wallet deductions.

← PreviousAuthentication & Signing Next →Rate Limits