Skip to content

Errors

All /v1 errors use the standard OpenAI error envelope, so the OpenAI SDK raises the matching typed exception automatically:

{ "error": { "message": "...", "type": "invalid_request_error", "param": null, "code": "invalid_api_key" } }

Self-correcting fields

Some errors add optional fields alongside the standard ones so an agent can recover without a human. They’re additive — the OpenAI SDK ignores unknown keys, so the envelope stays wire-compatible:

Field	Meaning
`hint`	What to do next (e.g. how to send a valid key, how to back off)
`docs_url`	The docs page that explains the fix
`did_you_mean`	The likely-intended value for a bad enum/param

{ "error": { "message": "Invalid or missing API key", "type": "invalid_request_error",
  "param": null, "code": "invalid_api_key",
  "hint": "Send a valid key as `Authorization: Bearer sk-octo_...`.",
  "docs_url": "https://docs.omniocto.com/getting-started/authentication" } }

Error table

HTTP	`type` / `code`	When	SDK exception
`401`	`invalid_request_error` / `invalid_api_key`	Missing or invalid API key	`AuthenticationError`
`403`	`insufficient_quota`	Workspace suspended or out of credits	`PermissionDeniedError`
`404`	`invalid_request_error`	Unknown `previous_response_id` / `conversation` / response id / model	`NotFoundError`
`400`	`invalid_request_error`	Malformed request body; `store:false` combined with `background:true`	`BadRequestError`
`422`	`invalid_request_error`	`Idempotency-Key` reused with a different request body	`UnprocessableEntityError`
`429`	`rate_limit_error`	Per-key or per-workspace rate limit exceeded (carries a `retry-after` header)	`RateLimitError`

Handling errors with the OpenAI SDK

from openai import (
    AuthenticationError,
    PermissionDeniedError,
    NotFoundError,
    BadRequestError,
    UnprocessableEntityError,
    RateLimitError,
)

try:
    resp = client.responses.create(model="claude-sonnet-4-6", input="hi")
except AuthenticationError:
    ...  # bad/missing key — see Authentication
except PermissionDeniedError:
    ...  # workspace suspended or out of quota — see Usage & billing
except RateLimitError as e:
    ...  # back off using the retry-after header — see Rate limits

Authentication for 401s.
Usage & billing for 403 insufficient_quota.
Rate limits for 429s.
Statefulness for 404s on unknown ids and 422s on idempotency conflicts.