Gateway errors

The gateway answers a refused request with an HTTP error status and this body:


{
  "error": {
    "message": "Usage allowance exhausted",
    "type": "insufficient_quota",
    "code": "usage_limit_exhausted",
    "param": null
  }
}

code is the specific reason when there is one. Every /v1 response has an x-request-id header.

Limit and product errors

Status	`type`	`code`	Cause
402	`permission_error`	`model_not_entitled`	No usage limit on the product applies to the request.
429	`insufficient_quota`	`usage_limit_exhausted`	A usage limit has too little allowance left in the billing period.
429	`rate_limit_error`	`rate_limited`	A rate limit is full for its window.
503	`server_error`	`product_not_configured`	The product has no provider account for the provider, or the project has no default product.

A rate_limited response has a Retry-After header with the number of seconds to wait. usage_limit_exhausted and product_not_configured responses have x-should-retry: false, so the OpenAI SDK does not retry them.

See Configure a product for usage limits and rate limits.

Other errors

401 or 403: the customer was revoked, deleted, or suspended. See Authentication.
503 service_unavailable with Retry-After: 1: the gateway is shutting down. Retry after one second.

When the gateway ends a stream itself, its last event carries the same error object, and no [DONE] event follows.

Handle errors in code

The Client SDK’s chat methods and the OpenAI SDK reject with the OpenAI SDK’s APIError. It has status, type, code, and headers:


import { APIError } from 'openai'
 
try {
  await client.chat.complete(request)
} catch (error) {
  if (error instanceof APIError && error.code === 'rate_limited') {
    retryLater(Number(error.headers?.['retry-after'] ?? 1))
  } else if (error instanceof APIError && error.code === 'usage_limit_exhausted') {
    showUpgradeOptions()
  } else {
    throw error
  }
}

An error from a stream’s last event has no status. Revoked, deleted, and suspended customers raise CustomerAccessInvalidatedError instead.