Reference
Error Codes
Every API response includes a status field ("success", "pending", or "failed"). When a request fails at the API level, an error_code field indicates the category of error. Payment-level outcomes (declined card, insufficient mobile money balance) are different — those use transaction_status and processor_response.
| Code | Label | Meaning & Next Steps |
|---|---|---|
00 | Success | Request processed successfully. |
90 | Validation Error | Invalid JSON structure or missing required fields. Check your request body against the parameter table. |
91 | Auth Error | API key is missing, invalid, or blocked by IP whitelist. Verify your credentials in the dashboard. |
92 | Not Found | The resource (transaction, payment link, etc.) does not exist or belongs to a different account. |
93 | Idempotency Error | An idempotency key conflict was detected. Use a unique key per request. |
99 | Server Error | Unexpected internal error. Safe to retry after a short delay. Contact support if persistent. |
Status vs Error Code Explained
These two concepts operate at different layers:
| Field | Layer | Meaning |
|---|---|---|
status: "success" | API level | The request was accepted and a response was produced. Does not mean the payment succeeded. |
status: "pending" | Payment level | Transaction initiated; awaiting customer authorization (e.g. STK push). |
status: "failed" | Payment level | Payment declined or rejected by the provider or customer. |
error_code | API level | Specific error category (see table above). Only present when the API itself could not process your request. |
Example
A charge request that triggers an STK push returns
status: "success" (the API accepted it) and transaction_status: "pending" (the payment is waiting for the customer). Later, if the customer rejects the push, your webhook receives status: "failed" — not an error_code.