GATEWAY_TIMEOUT — Upstream call timed out

Summary

A request to an upstream dependency — usually the LLM provider — exceeded our timeout budget. The request can be safely retried with an idempotency key.

HTTP status

504 Gateway Timeout. Standard envelope.

Example response

{
  "success": false,
  "error": {
    "code": "GATEWAY_TIMEOUT",
    "message": "Upstream LLM provider timed out after 60 seconds.",
    "request_id": "req_01HXJZK4ABCDEF",
    "doc_url": "https://docs.surveycoder.io/errors/gateway-timeout"
  }
}

Why this happens

• LLM provider latency spike.
• An unusually long verbatim or large batch pushed the call past the 60s budget.
• Transient network issue between our edge and the provider.

How to fix it

1. Retry with backoff. Wait 2s, 4s, 8s. Use an idempotency key so the original request can’t double-charge if it actually completed.
2. For large async jobs, the pipeline retries internally — you should rarely see GATEWAY_TIMEOUT on async; it’s usually a sync POST /v1/code with a wide batch.
3. If you consistently see it on a specific question, the verbatims may be unusually long. Split the batch into smaller chunks (10-20 at a time).
4. Check the status page — we post about provider-side incidents.

Related

• SERVICE_UNAVAILABLE
• CODING_FAILED
• Idempotency