Handle rate limits by API family
Recognize gateway and HTTP throttling signals without turning a delayed payment into a duplicate.
Recognize the two documented signals
The rate-limit guide describes a Payment API response in Classic form encoding and a system-wide HTTP response. They are different signals. The guide does not publish a requests-per-second quota, a reset window or a guaranteed Retry-After header. Do not add guessed limits to a client library. Scope Documented signal Interpretation Classic-format Payment API response=3, response_code=301, responsetext=Rate limit exceeded The gateway is throttling this submission System-wide services HTTP 429 Too Many Requests May affect multiple services or too many simultaneous connections from one IP REST Payments Use HTTP status and the JSON response/error contract Do not parse a REST body as a Classic query string or assume a documented Classic field is always present
Decode a Classic rate-limit result
For a Classic form-encoded response, read the actual fields. This parser is deliberately limited to that format; the REST backend requires its own JSON and HTTP handling. export function isClassicRateLimit(responseText) { const fields = new URLSearchParams(responseText); return fields.get('response') === '3' && fields.get('response_code') === '301'; }
Apply backpressure before another attempt
NMI advises waiting instead of immediately retrying, reducing simultaneous connections and checking repeated credential failures, which can temporarily lower limits. The following queue policy is an application recommendation, not a gateway timing contract. Pause the affected worker queue and reduce its concurrency. Check whether repeated authentication errors are driving requests. For read-only polling, resume with a bounded application-defined delay and avoid synchronized bursts. For payment writes, retain the attempt and determine its outcome before permitting a new submission. Escalate persistent throttling with redacted timestamps, request family and outcome details.
Keep retry decisions separate from throttling
A rate-limit signal is not a general license to replay a sale. Distinguish a definite rejection from a connection lost after submission. A response body you cannot parse, a timeout or a server error leaves a potentially unknown payment outcome. Query and reconcile the existing attempt instead of generating a new token and charging immediately. Do not attach automatic POST retry middleware to payment requests simply because the HTTP client can retry 429 or 5xx. Errors and uncertain outcomes Payment outcome codes
Verify the client behavior locally
Use fixtures to confirm that the Classic parser identifies code 301, an HTTP 429 pauses the correct queue and a malformed JSON payment response remains unknown. Keep polling/export workloads bounded so they do not compete unnecessarily with checkout. This guide provides no claim about a merchant-specific throughput allowance.