ERROR LIBRARY
AI API, Codex, and Claude Code Error Library
Start with the original status or error text, then isolate request, authentication, model, network, gateway, and client configuration failures. Every guide includes a minimal reproduction, a verification path, and redaction boundaries.
A consistent diagnostic sequence
- 01
Preserve evidence
Record the status, response body, request ID, UTC time, and client version.
- 02
Reduce the request
Hold the host, key, and model constant while changing one variable at a time.
- 03
Locate the response layer
Separate the client, network proxy, CodeNodex gateway, and model upstream.
- 04
Verify and redact
Retest the recovery scope and remove credentials and business data before sharing evidence.
API response errors
Separate request, authentication, model, rate-limit, and upstream failures by HTTP status.
OpenAI API 400 Bad Request: troubleshoot parameters, JSON, and request format
Diagnose HTTP 400 responses from an OpenAI-compatible API by checking JSON, model parameters, endpoint paths, and client serialization with a minimal request.
Open diagnostic stepsHTTP 401API 401 Invalid API Key: authentication checks for Codex, Claude Code, and SDKs
Trace a 401 Invalid API Key response across the target host, credential source, authorization header, process environment, and client configuration.
Open diagnostic stepsHTTP 403API 403 Forbidden: troubleshoot permissions, account state, and policy denial
Diagnose API 403 responses caused by model access, project roles, account restrictions, source policies, or gateway authorization rules.
Open diagnostic stepsHTTP 404API 404 Model Not Found: check model IDs, base URLs, and routing
Separate an HTTP route 404 from model_not_found, then verify the API root, exact model ID, provider mapping, and account-visible model catalog.
Open diagnostic stepsHTTP 429API 429 Rate Limit: diagnose throttling, quota, balance, and retry behavior
Identify whether HTTP 429 comes from RPM, TPM, concurrency, quota, balance, or budget controls, then implement bounded backoff and load shaping.
Open diagnostic stepsHTTP 500API 500 Internal Server Error: bounded retries and upstream isolation
Diagnose API 500 responses with a minimal request, model comparison, request IDs, and controlled retries while avoiding repeated side effects.
Open diagnostic stepsHTTP 502API 502 Bad Gateway: troubleshoot proxies, upstreams, and response transport
Locate the layer producing HTTP 502, then test upstream DNS, TLS, Host/SNI, connection pools, timeouts, and SSE proxy behavior.
Open diagnostic stepsHTTP 503API 503 Service Unavailable: overload, maintenance, and recovery checks
Handle API 503 responses by stopping retry storms, reading recovery hints, narrowing the affected model or region, and restoring traffic gradually.
Open diagnostic stepsNetwork and streaming
Diagnose timeouts, connection resets, TLS certificates, and interrupted SSE streams.
API request timeout: diagnose connection, first-byte, generation, and client deadlines
Split API timeout diagnosis into DNS, TCP, TLS, time to first byte, generation, proxy, and total job deadlines before changing timeout values.
Open diagnostic stepsECONNRESETAPI ECONNRESET / Connection Reset: diagnose unexpected connection closure
Locate whether a reset occurs while writing, waiting for first byte, or reading a response, then test keep-alive reuse, proxy idle limits, and cancellation.
Open diagnostic stepsTLS / SSLAPI SSL Certificate Error: certificate chain, hostname, and proxy diagnosis
Diagnose API TLS failures by checking system time, requested hostname, certificate SANs, intermediate certificates, runtime trust stores, and intercepting proxies.
Open diagnostic stepsSSE STREAMOpenAI API Stream Disconnected: troubleshoot interrupted SSE responses
Diagnose interrupted OpenAI-compatible SSE streams by comparing non-streaming behavior, raw event framing, proxy buffering, idle timeouts, and client consumption.
Open diagnostic stepsClients and configuration
Resolve context limits, Codex configuration, Claude Code gateways, and MCP startup failures.
Context Length Exceeded: diagnose and reduce context-window usage
Break the context budget into instructions, conversation history, tool schemas, files, and output reserve, then reduce the right source instead of truncating blindly.
Open diagnostic stepsCODEX TOMLCodex config.toml Parse Error: unknown fields, nesting, and strict validation
Diagnose Codex config.toml parsing with the actual Codex version, resolved CODEX_HOME, backups, strict doctor checks, and an isolated temporary configuration.
Open diagnostic stepsCLAUDE GATEWAYClaude Code Gateway Connection Error: URL, authentication, and model routing
Troubleshoot Claude Code through an LLM gateway by validating the Messages base URL, authentication mapping, model aliases, streaming, and tool calls.
Open diagnostic stepsMCP SERVERMCP Server Failed to Start: process, transport, authentication, and tool discovery
Diagnose MCP startup from configuration scope through process or HTTP transport, initialize negotiation, tools/list, and one read-only tool invocation.
Open diagnostic steps