Error Handling

Understand the gateway's error response format, error types, HTTP status codes, and how to identify requests using gateway headers.

Error Response Format

All errors from the gateway follow a consistent envelope compatible with the OpenAI client libraries:

{
  "error": {
    "message": "Invalid authentication credentials.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Fields

Field	Type	Description
`error.message`	string	Human-readable description of what went wrong
`error.type`	string	Machine-readable error category (see below)
`error.code`	string \| null	Optional fine-grained error code within the type

Error Types

Type	HTTP Status	Description
`invalid_request_error`	`400`	The request body is malformed, missing required fields, or contains invalid values
`authentication_error`	`401`	The Bearer token is missing, invalid, or has been revoked
`rate_limit_error`	`429`	The request was rejected due to IP or provider rate limits
`provider_error`	`502`	The upstream provider returned an error or an unexpected response
`not_found_error`	`404`	The requested endpoint or resource does not exist
`service_unavailable`	`503`	No healthy provider is available to serve the requested model

Gateway Request ID

Every response — including errors — includes the header:

x-gateway-request-id: req_01j9xkz3p4q5r6s7t8u9v0w1

Include this ID when reporting issues. It uniquely identifies the request in the gateway’s logs.

Common Error Scenarios

Missing or invalid token

{
  "error": {
    "message": "Invalid authentication credentials.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Fix: Ensure your Authorization header is set to Bearer <your-token> and the token has not been revoked.

Unsupported model

{
  "error": {
    "message": "Model 'gpt-99' is not supported by this gateway.",
    "type": "not_found_error",
    "code": null
  }
}

Fix: Check the Health endpoint for the list of currently configured models.

Provider failure

{
  "error": {
    "message": "The upstream provider returned an error: upstream connect error or disconnect/reset before headers.",
    "type": "provider_error",
    "code": null
  }
}

Fix: Retry with exponential backoff. The gateway will have already attempted its configured retry count before surfacing this error. Check Health for provider status.

All providers in cooldown

{
  "error": {
    "message": "No healthy provider available for model 'llama-3.3-70b-versatile'. Please try again shortly.",
    "type": "service_unavailable",
    "code": null
  }
}

Fix: Wait for providers to exit cooldown (typically seconds to minutes) and retry.

Handling Errors in Code

RESPONSE=$(curl -s -w "\n%{http_code}" \
  https://your-gateway.workers.dev/v1/chat/completions \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}')

HTTP_STATUS=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | head -n -1)

if [ "$HTTP_STATUS" -ne 200 ]; then
  echo "Error $HTTP_STATUS: $(echo "$BODY" | jq -r '.error.message')"
fi

async function chat(messages) {
  const response = await fetch(
    'https://your-gateway.workers.dev/v1/chat/completions',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer <your-token>',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ model: 'gpt-4o', messages }),
    }
  );

  const requestId = response.headers.get('x-gateway-request-id');

  if (!response.ok) {
    const { error } = await response.json();
    throw Object.assign(
      new Error(error.message),
      { type: error.type, code: error.code, requestId }
    );
  }

  return response.json();
}

try {
  const result = await chat([{ role: 'user', content: 'Hello' }]);
  console.log(result);
} catch (err) {
  console.error(`[${err.type}] ${err.message} (request: ${err.requestId})`);

  if (err.type === 'rate_limit_error') {
    // inspect Retry-After header and back off
  }
}