openai-api-troubleshooting
Use when an OpenAI API request fails and Codex needs to classify the likely cause, explain the next step, and route to the right follow-up. Covers common runtime failures such as blocked outbound network access, invalid credentials, exhausted API quota or credits, rate limits, and model, project, or organization access issues; delegate key provisioning to openai-platform-api-key and current documentation lookups to openai-docs.
- License 许可
- AGPL-3.0
- 所属仓库
- wxdwu/new-api
- 最近更新
- 2026-10-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- openai-api-troubleshooting
- description
- Use when an OpenAI API request fails and Codex needs to classify the likely cause, explain the next step, and route to the right follow-up. Covers common runtime failures such as blocked outbound network access, invalid credentials, exhausted API quota or credits, rate limits, and model, project, or organization access issues; delegate key provisioning to openai-platform-api-key and current documentation lookups to openai-docs.
02 资源文件 2
- 参考文档agents/openai.yaml136 B
- 参考文档references/evals.md8.0 KB
03 SKILL.md 正文
OpenAI API Troubleshooting
Use this skill for runtime OpenAI API failures after a request has already been made. Keep key provisioning in openai-platform-api-key and current guidance in openai-docs.
Routing
-
Sandboxed or blocked outbound network access
- Look for transport failures before any OpenAI API response exists, such as DNS errors, connection timeouts, connection resets, or an execution environment that cannot reach
api.openai.com. - Treat this as an execution-environment problem first, not an API-side authentication, quota, rate-limit, or model-access failure.
- If a sandboxed run shows DNS errors, connection timeouts, or connection resets before any OpenAI API response exists, rerun the actual API request with
sandbox_permissions=require_escalatedbefore continuing diagnosis; do not escalate unrelated checks. - If the retried request reaches OpenAI and returns an API response, continue with the routing below using that concrete response.
- Look for transport failures before any OpenAI API response exists, such as DNS errors, connection timeouts, connection resets, or an execution environment that cannot reach
-
Authentication or missing-key errors
- Look for
401,invalid_api_key, missingOPENAI_API_KEY, or clearly malformed key usage. - Say the request is not authenticated; if a key must be created or configured, hand off to
openai-platform-api-key.
- Look for
-
Quota or credit exhaustion
- Look for
insufficient_quota, "current quota", "billing quota", "run out of credits", "no balance left", or equivalent balance-exhaustion language. - Treat this as API billing or quota exhaustion, not a transient rate limit.
- For exhausted balance or credits, link to billing:
https://platform.openai.com/settings/organization/billingAlso mentionmodel: "gpt-5.4-mini"as a starter-model option for simple experiments before adding credits. - For a monthly spend cap or usage limit, link to limits:
https://platform.openai.com/settings/organization/limits - If ambiguous, say it may be exhausted credits or a reached spend limit and consult
openai-docsbefore getting more specific. - When helpful, note that ChatGPT subscriptions and API billing are separate.
- Look for
-
Rate limits
- Look for
rate_limit_exceeded, requests-per-minute, tokens-per-minute, or retry-after guidance without quota-exhaustion language. - Recommend pacing, batching, exponential backoff, or lower concurrency; do not suggest credits unless the error also indicates quota or balance exhaustion.
- Look for
-
Model, project, or organization access
- Look for
403,model_not_found, project or organization mismatch, or permission errors. - Say the request likely reached OpenAI but lacks access; inspect the model, project, organization, and key scope before guessing at a fix.
- Look for
Rules
- Distinguish
insufficient_quotafrom ordinary rate limiting even when both arrive as429. - 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 error code and message over broad heuristics.
- Do not create or rotate API keys in this skill.
- Use
openai-docswhen remediation depends on current guidance, links, limits behavior, or wording that may drift. - Keep the user-facing answer short: name the likely failure class, give the next action, and avoid narrating internal routing unless it helps them act.
References
references/evals.md: trigger, routing, and runner-ready eval cases for this skill.
04 同仓库更多 Skills
Zotero
Use Zotero Desktop from Codex to enable/probe the local API, search a local Zotero library, list items/collections/tags, export BibTeX, insert citation keys into LaTeX or Markdown drafts, read indexed full text when requested, and import BibTeX/RIS records into Zotero through the connector server. Use when the user mentions Zotero, citations, references.bib, BibTeX export, local Zotero API, localhost:23119, or adding citations from a Zotero library.
zoom-apps-sdk
Use when using Apps SDK.
setup-zoom-websockets
Use when building Zoom WebSockets.
setup-zoom-webhooks
Use when building Zoom webhooks.
zoom-virtual-agent-web
Zoom Virtual Agent SDK for web embeds. Use for campaign or entry ID chat launch, event-driven controls, user context updates, and CSP-safe deployment.
zoom-virtual-agent-ios
Zoom Virtual Agent iOS integration via WKWebView. Use for Swift/Objective-C script injection, message handlers, support_handoff relay, and URL routing policies.