skills.rest
openai
openaiOFFICIAL
Explore all skills by this author →
WebsiteGitHub

openai-api-troubleshooting

Diagnose OpenAI API request failures and route to the correct remediation path.

5.3k|765|Updated Mar 4, 2026
Search Tags:#quota#error diagnosis#API key#Troubleshooting#Debugging#openai api#rate limit
One-click install
npx skills add https://github.com/openai/plugins --skill openai-api-troubleshooting
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: openai-api-troubleshooting
Source: https://github.com/openai/plugins/tree/main/plugins/openai-developers/skills/openai-api-troubleshooting
Command: npx skills add https://github.com/openai/plugins --skill openai-api-troubleshooting

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

When an OpenAI API request fails, error messages like 401, 403, or 429 can be ambiguous, and developers often misdiagnose quota exhaustion as rate limiting or blame credentials when the real issue is blocked sandbox networking. This Skill classifies the actual failure class and points to the correct next action.

Core Features & Use Cases

  • Failure Classification: Distinguishes transport failures (DNS errors, timeouts, connection resets) from API-side errors such as authentication, quota exhaustion, rate limiting, and model or project access issues.
  • Sandbox Escalation Guidance: Detects when a Codex sandbox blocks outbound network access and directs rerunning the actual API request with escalated permissions before further diagnosis.
  • Precise 429 Routing: Separates insufficient_quota (billing or credits) from ordinary rate_limit_exceeded, linking to the correct billing or limits settings page.
  • Use Case: Your API call returns 429 insufficient_quota inside a Codex session. The Skill identifies credit exhaustion, links to the organization billing page, and avoids suggesting backoff strategies that would not help.

Quick Start

Ask the assistant to diagnose why your OpenAI API request is failing and what to do next.

Frequently Asked Questions about openai-api-troubleshooting

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix a 401 invalid_api_key error from the OpenAI API?▼

A 401 invalid_api_key error means the request is not authenticated, usually due to a missing or malformed OPENAI_API_KEY. Verify the key is set correctly in your environment, and if a key must be created or configured, use the openai-platform-api-key skill rather than troubleshooting further.

What is the difference between 429 insufficient_quota and rate_limit_exceeded?▼

insufficient_quota means your API billing balance or credits are exhausted, requiring action on the billing or limits settings page. rate_limit_exceeded means you are sending requests too fast, fixed by pacing, batching, exponential backoff, or lower concurrency.

Why does my OpenAI API request fail with a DNS error inside Codex?▼

A DNS error, timeout, or connection reset before any API response indicates blocked outbound network access in the sandboxed execution environment, not an API-side problem. Rerun the actual API request with sandbox_permissions set to require_escalated, then diagnose based on the concrete API response.

What should I check when the OpenAI API returns 403 model_not_found?▼

A 403 model_not_found means the request reached OpenAI but lacks access to the requested resource. Inspect the model name, project, organization, and API key scope to find the permission mismatch before changing anything else.

When should I not use this troubleshooting skill?▼

Do not use it to create or rotate API keys, which belongs to openai-platform-api-key, or to look up current API syntax and documentation, which belongs to openai-docs. It only handles classifying failures after a request has been attempted.

Related Skills

Explore More Software Engineering Skills→
jboothomasjboothomas
1

add-voice-transcription

Transcribe WhatsApp voice notes to text using OpenAI Whisper.

Community
Intermediate
vtexvtex
39

marketplace-rate-limiting

Manage VTEX API rate limits with exponential backoff and circuit breaking.

Official
Advanced
zaziedlmzaziedlm

openai-knowledge

Retrieve official OpenAI API schemas, parameters, limits, and examples via MCP tools.

Community
Intermediate
MrJmpl3MrJmpl3

0048-laravel-http-client-resilience

Configure Laravel HTTP client timeouts, retries, and failure logging.

Community
Intermediate