Errors

NeraSika uses standard HTTP status codes. A 2xx means the request was accepted. A 4xx means it was rejected, and nothing was charged or sent.

Error formats

Most errors look like this:

{
  "success": false,
  "message": "Transaction type not allowed for merchant"
}

When fields fail validation, the response lists each field instead:

{
  "errors": {
    "phone": "Empty or invalid phone provided",
    "amount": "Amount must be a positive number with at most 2 decimal places"
  }
}

Check for errors first, then message.

Status codes

Status	Meaning	What to do
200 / 202	Success / accepted for processing.	Wait for the callback where there is one.
400	Invalid request, or a business rule stopped it.	Read errors or message, fix the request. Don’t retry unchanged.
401	Missing, invalid or expired token.	Get a new token and retry once.
403	Your account isn’t allowed to do this.	Check your account settings with Nerasol.
404	The transaction or mandate doesn’t exist or isn’t yours.	Check the ID.
429	Too many token requests.	Wait, and cache tokens.
500	Something went wrong on NeraSika’s side, or see the note below.	Check the status before retrying a payment, so you don’t charge twice.

Common errors

Message	Cause
Unknown field values provided. Please ensure only allowed fields are provided	The body has a field the endpoint doesn’t accept. Send only the documented fields.
Empty or invalid phone provided	phone is missing.
Amount must be a positive number with at most 2 decimal places	amount is zero, negative, has more than 2 decimals, or isn’t a number.
Invaid network operator / Chosen network not supported	network isn’t MTN, Telecel or AirtelTigo.
Empty or invalid merchant callback url	The callback URL is missing or not a valid URL.
Transaction amount of X is above the Y limit for merchant	The amount is over your limit for that transaction type.
X transactions not allowed for merchant	The network isn’t enabled for your account.
Transaction type not allowed for merchant	The transaction type isn’t enabled for your account.
Not enough merchant funds	Your balance can’t cover a disbursement or reversal.

Known quirks

These return 500 today instead of a 4xx:

• Merchant secret must be provided: the x-merchant-secret header is missing on the token request.
• Merchant is not active: your merchant account is deactivated. Contact Nerasol.

Retrying safely

Payment requests aren’t idempotent: sending the same collection twice creates two transactions. If a request times out or returns 500, don’t resend it straight away. Check whether the first one was created, using the transactionId if you got one, or wait for its callback.