ERROR DESK / API-ERRORS13 NOTES
Search the message
you actually received.
Status codes are the first branch. Provider codes, headers, and request state narrow the repair.
What this section covers
An HTTP status tells you which layer refused the request, not which line of code to change. A 429 can mean a per-minute window, a spent monthly quota, a concurrency ceiling, or a locked resource — four different fixes behind one number. A 401 and a 403 both look like “auth is broken” until you read the challenge header.
Each note below starts from an observable response: the status, the headers that came with it, the provider’s own error code, and the request identifier worth keeping. It then separates what the response proves from what still has to be checked before a retry or a code change is safe.
Status-code failures
Behaviour defined by HTTP itself, consistent across providers.
07API 429 Too Many Requests: read the limit before retrying
Distinguish API rate limits, quota exhaustion, concurrency limits, and resource locks from a 429 response and its headers.
- 429 Too Many Requests
- Retry-After
- RateLimit-Remaining: 0
API 401 vs 403: credential failure or permission failure?
Use the status, WWW-Authenticate challenge, token state, and resource policy to separate API 401 Unauthorized from 403 Forbidden.
- 401 Unauthorized
- 403 Forbidden
- WWW-Authenticate
API 400 Bad Request with a JSON body: a structured checklist
Debug malformed JSON, Content-Type mismatches, double serialization, invalid query encoding, and provider request-shape errors behind HTTP 400.
- 400 Bad Request
- invalid JSON
- Content-Type mismatch
API 422 validation errors: locate the field path that failed
Interpret 422 Unprocessable Content responses, nested validation paths, enum failures, business rules, and framework-specific error arrays.
- 422 Unprocessable Content
- validation_error
- loc array
API 409 Conflict: state collision, duplicate key, or idempotency misuse
Diagnose API 409 responses caused by stale versions, duplicate resources, in-flight operations, or reused idempotency keys.
- 409 Conflict
- duplicate resource
- version mismatch
API 502 vs 503 vs 504: choose the right recovery path
Separate bad gateway responses, temporary service unavailability, and upstream timeouts before adding API retries.
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
CORS preflight failed: compare the request and response policy
Debug CORS preflight failures caused by origin mismatches, missing methods or headers, credentials with wildcard origins, and redirect behavior.
- blocked by CORS policy
- preflight request failed
- No Access-Control-Allow-Origin
Provider-specific failures
Codes and messages that only one API emits, with its own recovery rule.
06OpenAI 429: insufficient_quota vs rate_limit_exceeded
Read the OpenAI 429 error code before applying backoff: account quota and a temporary request or token rate limit need different fixes.
- insufficient_quota
- rate_limit_exceeded
- tokens per minute
Anthropic 529 overloaded_error: retry without causing a storm
Handle Anthropic API 529 overload responses with safe retry boundaries, jitter, idempotency awareness, and request-ID preservation.
- 529
- overloaded_error
- request-id
Gemini API key not valid: environment, restriction, and endpoint checks
Debug Gemini API API_KEY_INVALID and invalid key errors across AI Studio keys, project restrictions, environment variables, and endpoint versions.
- API_KEY_INVALID
- API key not valid
- INVALID_ARGUMENT
Stripe webhook signature verification failed: check the three inputs
Resolve Stripe 'No signatures found matching the expected signature for payload' errors by checking endpoint secret, raw body, and signature header.
- Webhook signature verification failed
- No signatures found matching
- Stripe-Signature
GitHub REST API 401 Bad credentials: token and header checks
Debug GitHub REST API Bad credentials responses involving expired tokens, malformed Authorization headers, fine-grained access, and SSO authorization.
- 401 Bad credentials
- GitHub token expired
- Authorization: Bearer
Twilio error 20003: authentication against account, region, and credential type
Troubleshoot Twilio 20003 authentication errors caused by Account SID mismatch, Auth Token confusion, API key pairing, region, and subaccounts.
- Twilio 20003
- Authenticate
- Account SID
RELATED WORKBENCHES03
Reproduce it locally.
These tools take the same evidence the notes above describe and compute the result in your browser tab.
Layered verdict, evidence, redaction warnings, and next checks
Open incident decoder →T02CORS preflight request simulatorPreflight requirement, exact failure reasons, and corrected response policy
Open cors preflight lab →T03API rate-limit header analyzerRemaining budget, reset time, safe pace, and header conflicts
Open rate-limit analyzer →Section FAQ
Before you dig in
Which note should I open first?
Start from the status code you received. If the provider returned a narrower code inside the body — insufficient_quota, overloaded_error, API_KEY_INVALID — open that provider note instead, because the recovery rule differs from the generic status.
Do these notes cover GraphQL and gRPC?
The transport-level notes apply wherever HTTP status codes and headers are used, including GraphQL over HTTP. Codes carried inside a GraphQL response body are provider-specific and are covered only where a note names them.
CONTINUERELATED SECTIONS
Rate budget, authentication challenge, cache validator, and CORS policy all arrive as header fields.
Open section →Reliability deskAPI reliability protocolsRetry policy, idempotency, pagination, and error shape are architecture decisions, not implementation details.
Open section →Workbench indexAll six APITC toolsDecode, simulate, analyse, plan, diff, and compile — locally.
Open section →