APITC / ISSUE DESK01
APIs fail in layers.
Start with the evidence.
Paste the response you have. APITC separates transport, authentication, throttling, contract and provider errors—then gives you the next useful check.
- 40
- reference notes
- 6
- working labs
- 0 B
- pasted data sent
- 01Transportaccepted
- 02Authenticationaccepted
- 03Limitsblocked
- 04Contractnot tested
- 05Provideridentified
retry-after: 17 x-ratelimit-remaining: 0 x-request-id: req_8f17
VerdictThe current window is exhausted. Wait 17 seconds; retry with jitter. This is not evidence of exhausted account credit.
WORKBENCH / T01LOCAL
Response triage,
without the guesswork.
Drop in an HTTP transcript, JSON error, response headers, or the provider’s plain-text message. The decoder reports what it can observe, what remains unknown, and where to look next.
Evidence
HTTP 429: A rate, quota, concurrency, or resource lock limit blocked the request.
Retry-After is present; it should take precedence over a guessed delay.
The reported request window has no remaining capacity.
Next checks
01Parse Retry-After as either delta-seconds or an HTTP date before scheduling the next attempt.
No account · no upload · no endpoint calledOpen the full API error decoder and operating notes →
WORKBENCH INDEX6 TOOLS
Small tools for expensive mistakes.
Each workbench is narrow enough to explain its result. They share evidence locally and link to the protocol note behind every rule.
API response and error decoder
Paste an HTTP response, error body, headers, or provider message. Separate transport, authentication, throttling, validation, and upstream failures before changing code.
- Reads
- HTTP transcript, JSON error, headers, or plain text
- Returns
- Layered verdict, evidence, redaction warnings, and next checks
CORS preflight request simulator
Model a browser preflight without calling a remote server. Compare the requested origin, method, headers, and credentials against the response policy.
- Reads
- Origin, method, request headers, and server CORS headers
- Returns
- Preflight requirement, exact failure reasons, and corrected response policy
API rate-limit header analyzer
Read standard RateLimit fields, common X-RateLimit variants, Retry-After values, Shopify bucket headers, and reset timestamps in one local report.
- Reads
- Raw response headers
- Returns
- Remaining budget, reset time, safe pace, and header conflicts
Exponential backoff and idempotency planner
Build a bounded retry schedule, compare jitter strategies, and flag duplicate-side-effect risk for POST, PATCH, and webhook delivery workflows.
- Reads
- Method, attempts, base delay, cap, jitter, and idempotency
- Returns
- Attempt timeline, cumulative wait, and replay-risk notes
OpenAPI breaking-change impact checker
Compare two JSON OpenAPI documents by operation and schema meaning. Classify removed endpoints, newly required inputs, narrowed enums, and response changes.
- Reads
- Base and candidate OpenAPI JSON
- Returns
- Breaking, risky, and additive change ledger
LLM and MCP tool schema compiler
Compile a canonical JSON tool contract for OpenAI strict tools, Anthropic, Gemini, MCP 2025-11-25, or the MCP 2026 release candidate.
- Reads
- JSON Schema or provider tool wrapper
- Returns
- Target JSON, path diagnostics, repairs, and lossy-transform notes
DIAGNOSTIC ORDER5 LAYERS
Check the boundary
before the body.
Changing the JSON is wasted work when the request never passed authentication or the current rate window. APITC’s notes follow the same order as an incident review.
- 01DNS, TLS, proxy, gateway, timeout
Transport
Did the request reach the intended host?
- 02Credential, scheme, expiry, project
Authentication
Was the supplied identity accepted?
- 03Rate, quota, concurrency, resource
Limits
Which budget or lock stopped the call?
- 04Media type, schema, validation, version
Contract
Did the wire shape satisfy the endpoint?
- 05Request ID, product code, recovery rule
Provider
What narrower code did the API return?
ERROR INDEX13 FIELD NOTES
Search the message you actually received.
Statuses are the first branch. Provider codes, headers, and request state narrow the repair.
API 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.
→02API 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.
→03API 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.
→04API 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.
→05API 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.
→06API 502 vs 503 vs 504: choose the right recovery path
Separate bad gateway responses, temporary service unavailability, and upstream timeouts before adding API retries.
→07CORS 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.
→08OpenAI 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.
→09Anthropic 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.
→10Gemini 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.
→11Stripe 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.
→12GitHub 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.
→13Twilio 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.
→PROTOCOL ATLAS / DATASET 016 PROVIDERS
“Standard API” ends
at the wire.
A source-linked comparison of the authentication, throttling, pagination, webhook, and idempotency dialects that change client code.
REFERENCE DESK27 NOTES
Headers, reliability patterns, and contract behavior.
HTTP & API headers 6
Retry-After header: seconds vs HTTP dateRetry-After: 120 · Retry-After: Wed, 21 OctRateLimit-Limit, Remaining, and Reset: calculate a safe request paceRateLimit-Limit · RateLimit-RemainingIdempotency-Key header: scope, retention, and payload fingerprintsIdempotency-Key · duplicate payment preventionWWW-Authenticate header: read the API authentication challengeWWW-Authenticate · Bearer error=invalid_tokenAccess-Control-Allow-Origin: exact origins, wildcard, Vary, and credentialsAccess-Control-Allow-Origin · Vary: OriginETag and If-None-Match for API caching and safe writesETag · If-None-MatchAll header references →Reliability patterns 4
API retries: exponential backoff, jitter, caps, and stop conditionsexponential backoff · full jitterIdempotent POST requests: prevent duplicate payments, orders, and jobsidempotent POST · duplicate chargeAPI pagination: offset vs cursor under changing dataoffset pagination · cursor paginationRFC 9457 Problem Details: a useful API error response formatapplication/problem+json · type title status detail instanceAll reliability protocols →Agent & tool contracts 17
Fix “additionalProperties is required to be supplied and to be false”OpenAI schema errorFix OpenAI strict mode’s incomplete required arrayOpenAI schema errorFix an OpenAI tool schema with anyOf at the rootOpenAI schema errorFix “schema must have a type key” in OpenAI toolsOpenAI schema errorReduce Anthropic’s “Schema is too complex for compilation” errorAnthropic schema errorDebug Gemini MALFORMED_FUNCTION_CALL with a schema-first checkGemini function errorFix an MCP tool inputSchema whose root is not an objectMCP protocol errorJSON Schema to OpenAI strict tool compilerInteractive converterAll tool schema errors →ARCHIVE MAP8 SECTIONS
Every note has a section.
Each section opens with what it covers, how to read it, and the workbenches that apply the same rules.
Status codes are the first branch. Provider codes, headers, and request state narrow the repair.
13Reference deskHTTP and API header referenceRate budget, authentication challenge, cache validator, and CORS policy all arrive as header fields.
06Reliability deskAPI reliability protocolsRetry policy, idempotency, pagination, and error shape are architecture decisions, not implementation details.
04Contract deskLLM tool schema errorsProvider validators report a symptom at the root. The defect is usually several nodes deeper.
07Contract deskTool schema convertersMechanical repairs where intent is recoverable; explicit warnings where it is not.
04Contract deskProvider schema comparisonsField-level differences that change client code, not marketing feature tables.
03Contract deskAgent tool contract guidesPortability, prompt weight, and version safety decided up front instead of debugged later.
03Workbench indexAPITC workbenchesSix local-first tools that explain the result they return.
06EDITORIAL METHODPRIMARY SOURCES
Useful before searchable.
Every field note starts with an observable failure, gives a bounded diagnostic path, and names the provider or standards source behind the rule. Pages do not exist merely to repeat a keyword.
That structure is deliberate: a sitemap helps discovery, but descriptive internal links and genuinely useful pages are what make the archive navigable to people and crawlers.
Start with the response
you already have.
HTTP, JSON, headers, and provider messages.
Processed locally in your browser.