API Status Codes & Dispute
Resolution Guide

Business-level status codes returned in JSON responses for transactions (e.g., Airtime/Data), including the recommended dispute-resolution workflow and implementation guidance.

Document Type: Developer Reference Applies To: Transaction APIs Version: 1.0
Workflow Response Fields Status Code Definitions Implementation Guidance Examples

1) Dispute Resolution Workflow (Recommended)

Use the steps below to initiate, track, and resolve transactions consistently.

  1. Initiate a transaction by calling the appropriate endpoint. The API returns an orderId (or OrderID) in the JSON response.
  2. Query the transaction using the orderId via the Query API to retrieve the current status.
  3. Cancel failed/invalid transactions using the Cancel API (with the same orderId) if the order is confirmed failed or your business logic requires reversal after the retry window.
Retry BehaviorTypical
Some statuses (e.g., Network Unresponsive / On Hold) may be retried automatically every 5 minutes for up to 1 hour before cancellation.
ImportantBest practice
Always persist and reconcile by orderId. Do not assume success based on initial submission.

2) Response Fields (Typical)

A typical transaction response includes the following fields:

  • orderId — Unique transaction identifier generated by the platform.
  • statusCode — Numeric business status code (see table below).
  • status — Textual state group (e.g., ORDER_RECEIVED, ORDER_COMPLETED).
  • remark — Short status label (e.g., Success, Network Unresponsive).
  • description — Human-readable explanation.
Example Response (Success)JSON
{
  "orderId": "1234567890",
  "statusCode": 200,
  "status": "ORDER_COMPLETED",
  "remark": "Success",
  "description": "Transaction was successful."
}
Example Response (Network Unresponsive)JSON
{
  "orderId": "1234567890",
  "statusCode": 201,
  "status": "ORDER_COMPLETED",
  "remark": "Network Unresponsive",
  "description": "No response was received from the network. The transaction will be retried periodically before cancellation."
}

3) Status Code Definitions

The table below describes business-level status codes returned in API JSON responses.

Status CodesBusiness statuses
Status Code Status Remark Description
100 ORDER_RECEIVED Awaiting Processing Order has been received and is awaiting processing.
199 ORDER_RECEIVED Unspecified Error Unspecified error while receiving the order.
300 ORDER_PROCESSED Awaiting Network Response Transaction was sent and is awaiting a response from the mobile network operator.
399 ORDER_PROCESSED Unspecified Error Unspecified error while processing the order.
200 ORDER_COMPLETED Success Transaction completed successfully and a success response was received.
201 ORDER_COMPLETED Network Unresponsive No response received after 60 seconds. Retries occur every 5 minutes for up to 1 hour before cancellation. Network issues may resolve if tried later.
299 ORDER_COMPLETED Unspecified Error Unspecified error after completion stage.
400 ORDER_ERROR INVALID_CREDENTIALS The UserID and API key combination is not correct.
401 ORDER_ERROR MISSING_CREDENTIALS The URL format is not valid.
402 ORDER_ERROR MISSING_USERID UserID/Username field is empty.
403 ORDER_ERROR MISSING_APIKEY API key field is empty.
404 ORDER_ERROR MISSING_MOBILENETWORK Mobile network is empty.
405 ORDER_ERROR MISSING_AMOUNT Amount is empty.
406 ORDER_ERROR INVALID_AMOUNT Amount is not valid.
407 ORDER_ERROR MINIMUM_100 Minimum amount is 100.
408 ORDER_ERROR MINIMUM_50000 Minimum amount is 50,000.
409 ORDER_ERROR INVALID_RECIPIENT An invalid mobile phone number was entered.
410 ORDER_ERROR INVALID_API_ERROR1 API error.
411 ORDER_ERROR INVALID_API_ERROR2 API error.
412 ORDER_ERROR INSUFFICIENT_APIAMOUNT Transaction was unsuccessful and placed on hold; it will be retried periodically before cancellation.
413 ORDER_ERROR INVALID_API Invalid API configuration or API access not permitted.
414 ORDER_ERROR INVALID_PAYMENT_OPTION Invalid payment option.
415 ORDER_ERROR INSUFFICIENT_APISTOREDEALERAMOUNT Insufficient API store dealer amount.
416 ORDER_ERROR INSUFFICIENT_APISTOREAMOUNT Insufficient API store amount.
417 ORDER_ERROR INSUFFICIENT_BALANCE Insufficient balance.
418 ORDER_ERROR INVALID_MOBILENETWORK Invalid mobile network.
499 ORDER_ERROR Unspecified Error Unspecified order error.
600 ORDER_ONHOLD Network Error Transaction placed on hold due to a network error and may be retried.
601 ORDER_ONHOLD Your request cannot be processed at this time Temporary processing limitation; transaction may be retried automatically.
602 ORDER_ONHOLD Your account has been credited back for failed Txn Transaction failed and funds have been credited back (where applicable).
603 ORDER_ONHOLD The process failed Transaction failed during processing; follow dispute workflow for resolution.
604 ORDER_ONHOLD Transaction Failure Transaction failure indicated by downstream provider.
605 ORDER_ONHOLD Failed recharge Recharge attempt failed and may be retried or cancelled based on retry policy.
606 ORDER_ONHOLD By APIUser Transaction placed on hold by API user action or rule.
699 ORDER_ONHOLD Unspecified Error Unspecified on-hold error.
500 ORDER_CANCELLED By APIUser Transaction cancelled by API user.
501 ORDER_CANCELLED By Server Transaction cancelled by server logic.
506 ORDER_CANCELLED Server Busy Transaction cancelled due to server capacity constraints.
507 ORDER_CANCELLED Network Error Transaction cancelled due to network error.
508 ORDER_CANCELLED Your request cannot be processed at this time Transaction cancelled due to temporary inability to process.
509 ORDER_CANCELLED Your account has been credited back for failed Txn Transaction cancelled and credited back (where applicable).
510 ORDER_CANCELLED The process failed Transaction cancelled after processing failure.
511 ORDER_CANCELLED Transaction Failure Transaction cancelled after provider failure response.
512 ORDER_CANCELLED Request is not valid Request rejected as invalid and cancelled.
513 ORDER_CANCELLED Failed recharge Recharge failed and was cancelled.
514 ORDER_CANCELLED Transaction rejected Transaction rejected by downstream provider and cancelled.
515 ORDER_CANCELLED The receiver’s account is in the wrong state Recipient account state prevented successful completion.
516 ORDER_CANCELLED Not a valid subscriber Recipient is not a valid subscriber for the requested operation.
517 ORDER_CANCELLED Not eligible for this offer Recipient is not eligible for the requested offer.
518 ORDER_CANCELLED Subscriber not eligible Subscriber is not eligible for data purchase.
519 ORDER_CANCELLED Existing plan pending activation You already have a data plan yet to be activated.
520 ORDER_CANCELLED Invalid network user Recipient is not a valid user on the specified network (e.g., Globacom).
521 ORDER_CANCELLED Order already completed/cancelled/refunded Order is already in a terminal state and cannot be modified.
599 ORDER_CANCELLED Unspecified Error Unspecified cancellation error.
Implementation GuidanceSummary
  • Persist orderId immediately and use it as the primary reconciliation key.
  • Treat ORDER_ONHOLD / Network-related results as non-terminal until the retry window completes.
  • For terminal failures, call Cancel (where required) and surface a clear customer outcome (cancelled/refunded).
  • Log raw responses for dispute handling and customer support investigations.