Resources

Errors

The API reports errors in three forms.

1. HTTP 401 from the auth layer. The bearer token is missing, invalid or expired. This is not a JSON-RPC envelope:

json

{ "status": 401, "message": "Failed, Not authorized" }

2. JSON-RPC error. The request failed:

json

{ "jsonrpc": "2.0", "error": { "code": 400, "message": "{\"sender_phone\":[\"The sender phone field is required.\"]}" }, "id": "1" }

For validation errors, message is a JSON string that maps each field to its errors.

3. A business status inside result. The request was processed, but the operation was not completed:

json

{ "jsonrpc": "2.0", "result": { "transaction_id": "in8447D7EC98", "status": 409, "message": "..." }, "id": "1" }

Error Codes

Code	Message	Meaning
400	`{"field":["..."]}`	A required field is missing or badly formatted
400	Can only send KES or USD	Unsupported sender currency
400	Recipient currency not available for inbound transactions	Unsupported recipient currency
400	Error getting currency details	No active exchange rate for the currency pair
400	Partner balance and overdraw limit surpassed	Insufficient funds at commit
400	Top up partner balance	Insufficient funds at commit
401	Failed, Not authorized	The token is missing, invalid or expired. Log in again
401	Error Logging in	The credentials are incorrect
404	transaction not found	Unknown `transaction_id` or `request_id`
409	A transaction with a similar request_id has already been recorded.	`request_id` reused. The response returns the original `transaction_id`
409	A similar transaction was logged within the last hour. Please verify your transaction details before retrying.	Possible duplicate. See Idempotency
409	Transaction already committed	The transaction is not `LOGGED`
422	Currency not allowed for `<type>` transactions	Wrong currency for the channel
422	Amount exceeds the limit	Above your limits
422	Amount below allowed limit	Below your limits
500	Internal Server error / Something went wrong	Afrisend error. Retry with backoff, then contact support

Some messages continue with request-specific details.

Situation	Retry?
Network timeout on a log request	Yes, with the same `request_id`
Network timeout on `commitTransaction`	Call `checkTransactionStatus` first. Commit again only if the status is still `LOGGED`.
`401`	Log in again, then retry once
`400` / `409` / `422`	No. Fix the request first.
`500`	Yes, with exponential backoff