Core concepts

Errors & troubleshooting

Diagnose failed requests using HTTP status, metadata codes and trace IDs.

Read the complete failure

Record the endpoint, environment, HTTP status, metadata code, reference and trace ID. Redact keys and unnecessary customer details. Distinguish a network failure from an API rejection and a failed purchase.

Common errors

Code	Next step
ERR_TRANSACTION_FAILED	The purchase failed. When the response confirms a wallet refund, reconcile that outcome without treating it as a new refund instruction. Keep processing transactions pending and verify uncertain outcomes by reference.
ERR_MISSING_OR_INVALID_FIELDS	Check required fields, types and lengths.
ERR_INVALID_REFERENCE_FORMAT	Use only letters and digits.
ERR_REFERENCE_ALREADY_EXISTS	A transaction already uses this exact reference. Verify it first; generate a different reference for a new purchase.
ERR_INVALID_PRODUCT_CODE_OR_INACTIVE	The purchase product code is invalid or inactive. Fetch the current products and select an active product.
ERR_INSUFFICIENT_BALANCE	Check available wallet funds.
ERR_TRANSACTIONS_NOT_FOUND	This reference does not exist in the authenticated user account. Check the reference, account and environment.
ERR_INVALID_MOBILE_NUMBER	Send the phone number in the required format.

HTTP status and retry decisions

Choose the next step from the outcome

Request rejected
Read the error code and correct the input or access issue.
Purchase uncertain
Verify the saved reference before retrying. Keep processing orders pending.
Read request interrupted
Use bounded backoff. Respect Retry-After when supplied.

Status	Handling
400 / 422	Correct invalid input before retrying.
401 / 403	Check credentials and access.
404	Check the resource, product or transaction identifier.
409	Resolve the duplicate reference; do not blindly resubmit.
429	Reduce frequency. Respect Retry-After if supplied.
500 / 503	Reconcile purchases before retrying. Use bounded backoff for read-only requests.

Ask for help

Give support the details to investigate

Email [email protected] with a redacted request, response code, trace ID, timestamp and environment. Never include your API key.

Transaction error codes

ERR_REFERENCE_ALREADY_EXISTS: A transaction already has this exact reference. Verify that transaction before deciding whether to create a new purchase with another reference.
ERR_INVALID_PRODUCT_CODE_OR_INACTIVE: The product code submitted for purchase is invalid or inactive. Retrieve the current products and choose an active product before retrying.
ERR_TRANSACTIONS_NOT_FOUND: The reference does not exist in the authenticated user account. Check the original reference, account and environment.

Always check metadata.code; do not rely on HTTP status alone. See response codes and recommended handling.

Questions? Let’s work through them.

Having an issue or need help with your integration? Join the Strongmb Slack community to ask questions and get assistance from our team and other developers.

Keep API keys and customer details private when sharing examples.

Experiencing a service issue? Check Strongmb’s service status for incident updates.

Join our Slack community