Common Errors

PayFast uses conventional HTTP response codes to indicate failures.

4xx: Something is wrong with the request you sent (missing/invalid fields, bad signature, etc.).
5xx: A PayFast networking or application error.

Error response envelope

{
  "code": 400,
  "status": "failed",
  "data": {
    "response": false,
    "message": "Failure"
  }
}

Fields

Field	Type	Description
`code`	number	HTTP status code returned.
`status`	string	Text description of the overall result (e.g., `failed`).
`data`	object	Error details.
`data.response`	boolean	Usually `false` on failure.
`data.message`	string	Brief reason message, if present.

Error codes & how to fix

HTTP	Message (as returned)	What it means	Quick fix
400	Required variables not present in request	One or more required fields are missing.	Add all required headers/body fields (e.g., `merchant-id`, `version`, `timestamp`, `signature`).
400	Value for signature is not in the expected format	The `signature` is not a valid MD5 hex string.	Re-generate as lower-case MD5 of the canonical string.
400	API version is not valid	`version` header is missing/invalid.	Set `version: v1`.
400	Signature not present in headers	No `signature` header.	Include `signature` header.
401	Merchant not found	`merchant-id` is unknown.	Verify the correct account (sandbox vs live) and the 8-digit ID.
401	Request origin not recognised	Server IP could not be determined.	Ensure requests are server-to-server and `REMOTE_ADDR` is passed.
401	Request origin could not be verified	IP not on the whitelist (if enabled).	Add your server IP(s) under Recurring Billing → IP Whitelist, or disable whitelisting.
401	Merchant authorisation failed	Signature check failed.	Rebuild the signature (see checklist below).
404	Service / endpoint not found	Wrong path or no permission.	Check the endpoint URL and that your merchant has access.
429	Signature rate limit reached, please try again in a few minute	You hit the rate limit for signature checks.	Back off briefly and retry with spacing.
500	Application Error	Internal application error.	Retry later; if persistent, check Status API and contact support.
500	Communication Failure	Network issue reaching the API.	Retry; confirm DNS/network/firewall.

Signature troubleshooting (quick checklist)

Build pairs from the headers/body you’re sending plus passphrase.
Alphabetise by key, URL-encode every value, join with &.
Exclude signature and exclude testing=true (sandbox flag).
MD5 the resulting string → send lower-case hex as the signature.
Use the sandbox passphrase for sandbox and the live passphrase for production.
Timestamp must be fresh and include an offset, e.g. 2025-08-26T08:00:00+02:00.

Examples

Missing signature (400)

{
  "code": 400,
  "status": "failed",
  "data": {
    "response": false,
    "message": "Signature not present in headers"
  }
}

Bad signature (401)

{
  "code": 401,
  "status": "failed",
  "data": {
    "response": false,
    "message": "Merchant authorisation failed"
  }
}

🧭
Test connectivity quickly with Ping.

🔐
New to the signature flow? See the step-by-step guide in Authentication & Signature.