Account

Errors

Errors return a non-200 HTTP status and this body:

{ "error": { "code": "INVALID_API_KEY", "message": "The API key provided is incorrect or invalid." } }

Code	HTTP	Cause	Fix
`INVALID_API_KEY`	400	Header missing or wrongly named, key wrong, inactive or expired.	Send `MHS-GUARANTEEPAY-API-KEY` as a header with the current key from API Settings.
`IP_NOT_WHITELISTED`	403	Your server IP is not in the IP list.	Add the IP under Domains, or remove all IPs.
`INVALID_JSON_PAYLOAD`	400	Body is not valid JSON, or the endpoint path is wrong.	Send `Content-Type: application/json` and check the URL.
`INSUFFICIENT_SCOPE`	400	Key lacks the permission for this endpoint.	Edit the key and tick the permission.
`PLAN_LIMIT`	403	Monthly transaction quota reached.	Upgrade using `upgrade_url`.
`INVALID_URL`	400	Return or webhook URL is invalid, or its domain is not whitelisted or not active.	Use a full `https://` URL and whitelist its host.
`MISSING_FIELD`	400	`full_name` or `mobile_number` is empty.	Send all required fields.
`INVALID_EMAIL`	400	No valid email address.	Send a real email.
`INVALID_AMOUNT`	400	Amount is not a positive plain decimal.	Send e.g. `"150.50"`.
`INVALID_CURRENCY`	400	Currency not enabled for the brand.	Add it under Currency Settings.
`INVALID_JSON` / `INVALID_METADATA`	400	`metadata` is not an object or a valid JSON string.	Send an object.
`INVALID_CUSTOMER`	400	Customer email is suspended by the admin.	Unsuspend under Customers.
`CREATE_FAILED`	500	Database error while creating.	Retry later.
`INVALID_PP_ID`	400	Unknown `pp_id`, another brand's payment, or not refundable.	Use the `pp_id` returned by create charge with the same brand's key.
`SMS_NOT_FOUND` / `INVALID_STATUS` / `INVALID_PAYLOAD`	404 / 400	mark-sms-used could not find or update the SMS.	Check `trx_id`, `sender_key` or `sms_id`.

Other symptoms

Symptom	Likely cause	Fix
Payment stays pending	SMS not synced or not matched	Check Devices and SMS data.
Webhook never arrives	No `webhook_url`, non-2xx reply, redirect, or firewall	Open Transactions → Webhook log to see the exact HTTP code and response.