openai-api-troubleshooting

Use when an OpenAI API request fails or the user asks what an error means, including blocked access to api.openai.com, 401 invalid_api_key, missing OPENAI_API_KEY, 429 insufficient_quota, 429 rate_limit_exceeded, or 403 model_not_found. Classify the failure, name the next step, route credential setup to openai-platform-api-key, and current guidance to openai-docs.

Jump to install

Repository: openai/openai-developers-for-cursor
Last source activity: June 23, 2026 at 19:38
Detected SKILL.md language: English
Stars: 5
Forks: 2

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/openai/openai-developers-for-cursor --skill openai-api-troubleshooting

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

OpenAI API Troubleshooting

Use this for runtime OpenAI API failures after a request has already been made. Keep key setup in openai-platform-api-key and current guidance in openai-docs.

Routing

Sandboxed or blocked outbound network access

Treat DNS errors, connection timeouts, connection resets, or inability to reach api.openai.com before any API response as transport problems first.
If the failure came from a sandboxed or restricted run, explicitly recommend retrying the actual request with network access enabled or outside that restriction; only classify API-side auth, quota, rate-limit, or model access after a concrete OpenAI response exists.

Authentication or missing-key errors

Route 401, invalid_api_key, missing OPENAI_API_KEY, or malformed-key cases to authentication.
If a key must be created or configured, explicitly hand off to openai-platform-api-key; do not stop at generic "create a fresh key" advice.

Quota or credit exhaustion

Treat insufficient_quota, "current quota", "billing quota", "run out of credits", or "no balance left" as billing/quota exhaustion, not ordinary throttling.
For exhausted credits, prompt the user to add credits and include Add API credits. Do not purchase credits or change billing settings.
Link usage caps to https://platform.openai.com/settings/organization/limits.
If ambiguous, say it may be credits or a spend limit and consult openai-docs; when useful, note that ChatGPT subscriptions and API billing are separate.

Rate limits

Route rate_limit_exceeded, requests-per-minute, tokens-per-minute, or retry-after guidance without quota language to throttling.
Recommend pacing, batching, exponential backoff, or lower concurrency; do not suggest buying credits unless the error also indicates quota exhaustion.

Model, project, or organization access

Treat 403, model_not_found, org/project mismatch, or permission failures as reached-OpenAI-but-not-authorized cases.
Check the model, project, organization, and key scope before guessing.

Rules

Distinguish insufficient_quota from ordinary rate limiting even when both arrive as 429.

Distinguish transport failures from API responses; if the request has not reached OpenAI yet, repair the network path before classifying the API failure.

Prefer the concrete API error code and message over generic heuristics.

Keep user-facing answers short: likely class, reason, next action.

Do not rotate or create keys here.

Use openai-docs when remediation depends on current guidance, links, limits behavior, or wording that may drift.