OpenAI API Setup and Error Reference
A compact reference for OpenAI API setup, Responses API, common errors, rate-limit dimensions, request IDs, quota, structured outputs and key security debugging.
| Item | Value | Debug check |
|---|---|---|
| Base URL | https://api.openai.com/v1 | Use this prefix for direct OpenAI API calls. |
| Responses API | POST /v1/responses | Start new projects here; supports text, tools, streaming and multimodal inputs. |
| Chat Completions | POST /v1/chat/completions | Common in older apps and compatibility layers; check Responses API for newer features. |
| Authentication | Authorization: Bearer ... | For 401, check credential, organization, project and forwarding proxy. |
| Organization/project | OpenAI-Organization / OpenAI-Project | Specify them when you use multiple organizations, projects or legacy credentials. |
| Request tracking | x-request-id / X-Client-Request-Id | Log request IDs in production; supply your own client request id for timeout/network cases. |
| Rate-limit headers | x-ratelimit-* | Record remaining requests/tokens and reset times to drive backoff. |
| Batch | /v1/batches | For non-real-time batch workloads; evaluate separately from realtime requests. |
| HTTP | Type / scenario | Meaning | Check first |
|---|---|---|---|
400 | invalid_request_error | Invalid parameter, message, tool or JSON shape. | Check endpoint, model, input/messages, tool schema and max tokens. |
401 | invalid_authentication | Authentication failed or credential is incorrect. | Check Bearer credential, organization/project headers, env vars and proxy forwarding. |
403 | unsupported_country_region | Country, region or access condition is unsupported. | Check account, region, network egress and organization permissions. |
404 | not_found | Endpoint, model or resource was not found. | Check URL, model name, file/batch/response id. |
409 | conflict | Resource state or concurrent operation conflict. | Re-read resource state and retry. |
429 | rate_limit_exceeded | Request or token rate limit hit. | Use x-ratelimit-* headers, exponential backoff and lower concurrency. |
429 | insufficient_quota | Credits, balance or monthly spend limit exhausted. | Check billing, usage limit, project budget and org limits. |
500 | server_error | Server-side error. | Log request id and retry with backoff. |
503 | service_unavailable | Temporary unavailability or high load. | Retry with backoff; optionally switch model or delay work. |
| Dimension | Form | Notes |
|---|---|---|
| RPM | requests / minute | Request-count dimension; bursts and concurrency often hit it first. |
| TPM | tokens / minute | Input, output and estimated tokens can all matter. |
| RPD / TPD | daily limits | For large usage, inspect project and organization limits. |
| Usage limits | monthly spend | 429 quota errors are usually billing/spend-limit problems, not simple throttling. |
| Shared limits | model family | Some model families share limits, so switching within the family may not help. |
- Common community issues cluster around 429, quota, Responses/Chat Completions migration, model not found, structured-output schemas, streaming, request IDs and leaked API keys.
- Evaluate the Responses API first for new projects; Chat Completions remains common in older apps and compatibility layers.
- For 429, distinguish rate limit from quota: one is short-window request/token pressure, the other is usually billing, credits or monthly spend limit.
- Log x-request-id in production; for timeouts or network errors, supply X-Client-Request-Id to help later troubleshooting.
- OpenAI rate limits can be enforced across RPM, RPD, TPM, TPD, IPM and shared model-family limits at organization or project level.
- Do not put OpenAI API keys in browsers, mobile apps or public repositories; frontend calls should go through your backend or a controlled proxy.
Source: official OpenAI API reference, Responses API, error-code and rate-limit documentation, plus recurring community troubleshooting topics. Community posts are used as topic signals only; official docs and console limits remain authoritative.
This OpenAI API setup and error-code reference helps debug OpenAI API 401, 403, 404, 429 rate limit, 429 quota, 500, 503, Responses API failures, Chat Completions migration, structured-output schemas, model not found, missing request IDs and rate-limit header handling.
Related search intents: OpenAI API setup · OpenAI API errors · OpenAI API 429 · OpenAI rate limit · OpenAI quota exceeded · OpenAI insufficient_quota · OpenAI x-request-id · Responses API · Chat Completions · OpenAI structured outputs · OpenAI model not found · OpenAI API key leaked · OpenAI-Project header · OpenAI-Organization header
FAQ
Should new projects use Responses API or Chat Completions?
Start with the Responses API for new projects. Chat Completions is still common for older apps, compatibility layers and high-migration-cost systems. Migration needs more than endpoint replacement: check input shape, tools, streaming and response parsing.
What is the difference between OpenAI 429 rate limit and quota?
Rate limit usually means too many requests or tokens in a short window. Quota usually means credits, billing, monthly usage or project budget limits. Many “I still have balance” cases are actually TPM/RPM or shared model-family limits.
Why can I get 429 even with balance left?
RPM, TPM, RPD, TPD, IPM or shared model-family limits may trigger before balance is exhausted. Inspect the response body and x-ratelimit-* headers before deciding whether to back off, lower concurrency or request higher limits.
How do I fix insufficient_quota?
Check billing, usage limits, project budgets, organization limits and payment status. Plain retries usually do not help; recently changed billing or limits may also have propagation delay.
What is x-request-id for?
It is the troubleshooting ID OpenAI generates for each request. Log it in error reports and user-copyable diagnostics; for 500/503, streaming interruptions or support escalation, it is safer than sharing full prompts.
Are OpenAI-Organization and OpenAI-Project required?
Not always. They are useful when you have multiple organizations, multiple projects or legacy credentials and need deterministic routing, billing and quota attribution.
Why do I get model_not_found or 404?
Common causes are stale model names, missing project permission, wrong endpoint, or mixing Responses API and Chat Completions parameters. Verify the official model page and project access first.
Why do structured outputs return 400?
Common causes include unsupported JSON Schema features, incomplete required fields, incompatible additionalProperties settings, or mixing tool schemas with response_format. Start with a minimal schema and add fields gradually.
Why did a streaming response cut off midway?
Separate provider errors from proxy timeouts, browser/edge runtime limits and clients that do not consume the SSE stream correctly. Log request IDs and consider shorter outputs or backend streaming relay.
What should I do if an API key leaked or was committed to GitHub?
Revoke the old key immediately, create a new one, inspect usage and billing, rotate deployment environment variables, and check logs, frontend bundles and mobile apps for remaining copies. Do not only delete it from Git history.