Hi Square Team,
I’m following up on my previous discussion regarding the 502 Bad Gateway response from the /payments API, as I haven’t received a response to my last update.
In the previous thread, I shared that:
-
The incident occurred on 12-06-2026, not during the service disruption on 22-06-2026 that was referenced.
-
Our Application ID is: sq0idp-IbtUpw5WWJkQOIPL8qTOtQ.
-
The customer was successfully charged, but the API returned a 502 HTML error page instead of the expected JSON response.
-
Because the response did not contain a payment_id, our application was unable to reconcile or update the transaction status.
-
We are already subscribed to payment webhooks, but our current flow depends on the payment_id returned by the synchronous /payments API response.
Our main questions are:
-
Is there any way to identify or retrieve the payment when the /payments API returns an HTML 502/503 response after the payment has already been processed?
-
What could cause Square to return a Cloudflare 502 HTML page instead of the standard JSON error response?
-
What is the recommended integration pattern for handling these scenarios so that successful payments are not left unreconciled when the synchronous API response is lost?
If anyone from the Square team could investigate this using the Application ID above or provide guidance on the recommended recovery strategy, it would be greatly appreciated.
Previous Post : Bad gateway Error code 502(payments api)
Also if your team can add below email addresses to Slack channel then it will be more helpful.
[email protected]
[email protected]
Thank you.
A 502 after a successful charge should be treated as an unknown outcome. If you used an idempotency key, retry with the same key and rely on webhooks to reconcile the payment. The Square team should also be able to trace the transaction using your Application ID, timestamp, and idempotency key, and hopefully explain why a Cloudflare HTML 502 was returned instead of a JSON error.
@kishanv Yes, in general I’d recommend handling these errors by retrying the request (and leveraging idempotency keys to ensure that a duplicate request is not processed by accident).
Unfortunately this specific incident from 12-06-2026 is out of the retention window for the logs we have on our side. Have there been any more recent occurrences since then? If so, if you can provide the timestamp (date, time, and timezone) I’m happy to see what I can find in the traces.
Thanks for your response.
I have a follow-up question regarding your recommendation to retry requests using idempotency keys.
Could you please clarify what the recommended idempotency key reuse period is? Specifically:
- How long should the same idempotency key be reused when retrying a request?
- What retry duration or maximum retry window do you recommend?
- Is there a recommended retry strategy (for example, exponential backoff with jitter), and are there any limits on the number of retry attempts?
We’d like to align our implementation with Square’s best practices to avoid duplicate processing while ensuring reliable request handling.
@kishanv Good questions!
How long should the same idempotency key be reused when retrying a request?
I’d recommend thinking about this in terms of request uniqueness rather than a specific timeframe. You should only generate a new key when the user/system intentionally initiates a new attempt (e.g., customer clicks “Pay” again after a hard decline). Upon receiving a request, Square will check whether a request has already been processed from that application ID with a matching idempotency key, and ignore the inbound request if so.
What retry duration or maximum retry window do you recommend?
Square doesn’t have a set recommendation here, since what is considered a reasonable amount of time to keep the user waiting while retrying requests will vary based on your use case. In general setting a ~30-60s retry window makes sense.
Is there a recommended retry strategy (for example, exponential backoff with jitter), and are there any limits on the number of retry attempts?
There’s no hard limit to retry attempts, but we do recommend using exponential backoff with jitter. Assuming a limited retry window, in practice that usually means 3-5 retry attempts.