Errors
Check status in the response. Failures return an error type you can act on; most issues are caused by incorrect usage (signature, limits, missing fields), so review your implementation before contacting support.
Error response
{ "data": { "errMessage": "bankAccount_not_found", "message": "Uygun hesap bulunamadı" }, "status": 400, "app_version": "iraqpay-v0.1.0" }Error types
| errMessage | HTTP | Description |
|---|---|---|
| error_invalid_sign | 403 | Signature mismatch or missing appKey/sign. Check the raw body you signed. |
| error_site_not_found | 404 | No integration for this appKey, or your site was disabled. |
| not_authorized | 403 | IP allowlist: your IP is not authorized. |
| error_validation | 400 | Missing/invalid fields; message lists them. |
| error_invalid_bank | 404 | bankId unknown or not enabled for your site. |
| bankAccount_not_found | 400 | No wallet account can currently take this amount (limits reached or no active account). Retry later or offer another method. |
| error_transaction_blacklisted | 403 | The user or recipient is blacklisted. |
| amount_below_min / amount_above_max | 400 | Outside your site's or the method's limits. |
| amount_not_multiple | 400 | Amount must be a multiple of the configured step (default 250 IQD). |
| invalid_iban | 400 | Recipient identifier doesn't match the method's format (withdraw). |
| insufficient_site_balance | 402 | Withdraw exceeds available treasury (see Balance). |
| error_transaction_not_found | 404 | Unknown transactionId/processId for your site. |
| internal_server_error | 500 | Unexpected issue; our team is notified. Retry with backoff. |