Errors (current)

Deprecated for new integrations

The Current API is deprecated for new integrations. It stays online indefinitely for backward compatibility — existing wiring doesn't need to change — but new builds should target v1 Errors instead.

Every error response shares the same envelope:

Example

json

{
  "response_code": "810",
  "response_message": "Electricity recharge transaction failed: 500 - Your meter number has been blocked and cannot purchase electricity. Please contact BPC.",
  "timestamp": 1718729782618,
  "developer_message": "com.tocchae.scratchPower.exception.TopupIntegrationServiceException",
  "errors": {}
}

Field	Type	Notes
`response_code`	string	Stable code — branch on this in your client
`response_message`	string	Human-readable, localised, safe to show users
`timestamp`	integer	Server-side unix millis
`developer_message`	string	Internal exception class — useful for support tickets, don't show to users
`errors`	object	Field-level validation details (when applicable)

General codes

Code	HTTP	Description
100	INTERNAL_SERVER_ERROR	Unexpected Error Occurred: `{0}`
101	BAD_REQUEST	`{0}` cannot be empty
102	NOT_FOUND	No `{0}` data found for id `{1}`
103	FORBIDDEN	`{0}` forbidden
104	BAD_REQUEST	Invalid MSISDN `{0}`
110	UNAUTHORIZED	Actor `{0}` does not have permission: `{1}`
115	FORBIDDEN	Actor `{0}` is not allowed to transact with actor `{1}`
120	BAD_REQUEST	Invalid method argument
130	BAD_REQUEST	No actor found with id: `{0}`
136	BAD_REQUEST	Some mandatory fields are empty
146	NOT_FOUND	No account found with reference: `{0}`
147	BAD_REQUEST	Invalid operation
150	BAD_REQUEST	Invalid parameters passed for actor search
151	NOT_FOUND	No actor found with Username: `{0}`
152	NOT_FOUND	No actor found with phone number: `{0}`
156	BAD_REQUEST	Username cannot be empty
157	BAD_REQUEST	Password cannot be empty
158	UNAUTHORIZED	Authentication failed
159	BAD_REQUEST	Password and confirmation password mismatch
163	NOT_FOUND	No accounts retrieved for debited actor with corresponding currency: `{0}`
164	NOT_FOUND	No accounts retrieved for credited actor with corresponding currency: `{0}`
166	NOT_FOUND	No accounts retrieved for agent with corresponding currency: `{0}`
172	BAD_REQUEST	Please specify either requester Actor details or ID
174	BAD_REQUEST	Please specify the electricity meter no.
175	BAD_REQUEST	Please specify either Beneficiary Actor details or ID
176	BAD_REQUEST	Please specify the electricity meter no.
182	BAD_REQUEST	Please specify the Debited account ID reference
183	BAD_REQUEST	Please specify the Credited account ID reference
184	BAD_REQUEST	Please specify the account ID reference
187	BAD_REQUEST	This operation is in an invalid state for any further processing. Operation status is: `{0}`
201	BAD_REQUEST	Requester and Beneficiary must be different
251	BAD_REQUEST	You have insufficient balance to perform this operation
600	BAD_REQUEST	Please specify either Organisation Code
601	BAD_REQUEST	No organisation found with id: `{0}`
602	BAD_REQUEST	Please specify either Organisation Code
603	BAD_REQUEST	Organisation Code passed does not correspond to an existing organisation in the system

Topup-specific codes

Code	HTTP	Description
800	BAD_REQUEST	Please enter a valid 11-digit electricity meter number
801	BAD_REQUEST	This meter number is not allowed for your organisation
805	BAD_REQUEST	Please enter an amount greater than `{0}`
810	INTERNAL_SERVER_ERROR	Electricity recharge transaction failed: `{0}`
811	INTERNAL_SERVER_ERROR	Electricity recharge transaction failed: Unable to call electricity provider. Please try again later.
815	INTERNAL_SERVER_ERROR	Electricity recharge validation failed: `{0}`
816	INTERNAL_SERVER_ERROR	Electricity recharge validation failed: Unable to call electricity provider. Please try again later.
817	BAD_REQUEST	Topup retries is not enabled for this transaction

810 / 815 sub-reasons

When a 810 or 815 comes back, response_message contains one of:

Reason	Message
`DUPLICATE_REQUEST`	Duplicate Request
`PREVIOUS_TRANSACTION_PENDING`	Previous transaction is still pending. Please wait a few minutes and try again.
`REQUEST_TIMEOUT`	Your request timed out. Please try again later or contact customer support if this persists.
`ENDPOINT_NOT_FOUND`	Recharge server is unreachable. Please try again later or contact customer support if this persists.
`METER_NO_FAILED_VALIDATION`	The meter number is invalid. Please make sure you entered a valid meter no.
`METER_NO_NOT_FOUND`	The meter number does not exist. Please make sure you entered a valid meter no.
`PURCHASING_BLOCKED`	Your meter number has been blocked and cannot purchase electricity. Please contact BPC.
`METER_BLOCKED`	Your meter number has been blocked and cannot purchase electricity. Please contact BPC.
`PURCHASE_AMOUNT_INVALID`	You have entered an invalid purchase amount.
`MIN_AMOUNT_ERROR`	Amount requested is less than the allowed amount.
`AMOUNT_NOT_ENOUGH`	Amount requested is less than the amount to pay charges.
`MAX_AMOUNT_ERROR`	Amount requested is more than the allowed amount.
`CONNECTION_REFUSED`	Recharge server is unreachable. Please try again later or contact customer support if this persists.
`UNABLE_TO_FIND_TRANSACTION`	The requested transaction does not exist. Please make sure you have given the correct operation ID.
`CANNOT_PROCESS`	Your request cannot be processed right now. Please try again later or contact customer support if this persists.

Handling timeouts

A timeout (REQUEST_TIMEOUT) means Scratch Power reached BPC but didn't get a response in time — the underlying transaction state is unknown. Do not re-send /api/topup/confirm. Use POST /api/topup/retry with the same meter_number + external_reference to ask BPC what actually happened.