Error Handling

Build resilient Responses API clients with retriable logic and clear failure handling.

POST/v1/responses

Name	Type	Description
400	Bad Request	Malformed Responses API payload
401	Unauthorized	Invalid bearer token
408	Request Timeout	Gateway timeout waiting for provider
429	Too Many Requests	Rate or quota limit exceeded
500	Internal Server Error	Unexpected TheRouter.ai failure
502	Bad Gateway	Provider-side error surfaced by gateway

Typed Error Payload

responses-error.json

{
  "error": {
    "code": 502,
    "type": "upstream_error",
    "message": "Provider unavailable",
    "metadata": {
      "provider": "openai",
      "request_id": "req_01JZR0BHZQEK7X8MKC0A44T04H",
      "retryable": true
    }
  }
}

Retry Policy

const retryable = new Set([408, 429, 500, 502]);

async function requestWithRetry(run: () => Promise<Response>) {
  for (let attempt = 0; attempt < 4; attempt += 1) {
    const res = await run();
    if (!retryable.has(res.status)) return res;
    const base = 250 * 2 ** attempt;
    const jitter = Math.floor(Math.random() * 100);
    await new Promise((r) => setTimeout(r, base + jitter));
  }
  return run();
}

Idempotent Retries

Include your own request correlation ID and make downstream tool actions idempotent before enabling automatic retries.