API Integration Debugging Prompt

Public field comparison

API Integration Debugging Prompt

API Integration Debugging Prompt

Diagnose API failures by checking requests, auth, payloads, rate limits, logs, retries, and safe fixes.

Diagnose API integration failures using request traces, contracts, authentication evidence, logs, controlled tests, and verifiable fixes.

—

Use this prompt to isolate API request, authentication, payload, transport, rate-limit, retry, webhook, and response-handling failures while producing an evidence-backed remediation and verification record.

API Contract Review
Integration Planning
Request Validation
Error Handling Review
Regression Testing
Release Verification

Diagnosing request and response contract mismatches
Tracing authentication, authorization, and signature failures
Investigating API timeouts, rate limits, and unsafe retries
Debugging webhook verification, replay, and deduplication issues
Verifying API fixes with contract, negative, and regression tests
Preparing evidence-backed API provider escalations

Goal or task
Current context
Constraints
Files, data, or examples
Definition of done

Debugging objective
System and API context
Failure evidence
API contract and provider documentation
Relevant code and configuration
Authorized actions and constraints
Test environment and commands
Acceptance criteria

Replace every bracketed placeholder before running. Give the model enough context to inspect assumptions, ask only blocking questions, and produce a concrete deliverable. For code prompts, include relevant files, errors, logs, and test commands.

In Codex, replace every bracketed variable with the API objective, system context, sanitized failure evidence, provider contract, relevant files, authorization limits, available test commands, and acceptance criteria. Attach or expose the relevant source files, redacted request and response traces, logs, schemas, documentation, configuration, and test fixtures. Confirm whether Codex may inspect files or run commands, then run the prompt in the authorized workspace.

Use this when you need a production-ready debugging result in Codex & Coding, not a generic brainstorm. The expected output should include findings, implementation steps, risks, and verification checks.

A payment client intermittently returns timeouts and duplicate-charge warnings after a retry change. Supply Codex with the client code, redacted traces, provider OpenAPI contract, idempotency documentation, retry configuration, correlation IDs, and sandbox test commands. The output should distinguish provider latency from unsafe retry behavior, propose a minimal patch, and document executed and unexecuted verification separately.

Expert

Expert

Codex

Codex

debugging

debugging

codex
Codex & Coding
api
debugging
integration

codex
api-debugging
api-integration
authentication
contract-testing
reliability

API Integration Debugging Prompt | AMO.ng

API Integration Debugging Prompt | AMO.ng

Diagnose API failures by checking requests, auth, payloads, rate limits, logs, retries, and safe fixes.

Diagnose API request, auth, payload, retry, rate-limit, webhook, and response failures with evidence-backed fixes and verification.

Prompt-body line comparison

Removed Added Unchanged context

−Act as a senior Codex & Coding specialist using Codex. Your task is: [Goal or task].
+Debug the API integration described below using Codex and produce an evidence-backed diagnosis, a safe remediation proposal, and concrete verification results.
 
−Context:
−- Current situation: [Current context]
−- Constraints: [Constraints]
−- Available materials: [Files, data, examples, URLs, logs, notes]
−- Success criteria: [Definition of done]
+Inputs
+- Debugging objective: [Debugging objective]
+- System and API context: [System and API context]
+- Failure evidence: [Failure evidence]
+- API contract and provider documentation: [API contract and provider documentation]
+- Relevant code and configuration: [Relevant code and configuration]
+- Authorized actions and constraints: [Authorized actions and constraints]
+- Test environment and commands: [Test environment and commands]
+- Acceptance criteria: [Acceptance criteria]
 
−Workflow:
−1. Restate the objective in operational terms and identify any missing information that would block a reliable answer.
−2. Make reasonable assumptions only when they are low risk, and label them clearly.
−3. Produce the main deliverable for "API Integration Debugging Prompt" with enough detail that a skilled operator can execute it immediately.
−4. Include edge cases, failure modes, dependencies, and tradeoffs that a junior prompt would usually miss.
−5. Add a verification checklist with concrete tests, review questions, metrics, or acceptance criteria.
−6. End with the smallest safe next action.
+Input requirements
+Treat the following as blocking prerequisites for a confirmed diagnosis: the failing endpoint or operation, expected behavior, an observed symptom such as an error response or timeout, and the boundaries of authorized inspection or execution. Request clarification when any of these are absent, when evidence conflicts materially, or when a test could affect production data or external users. If clarification is unavailable, continue only with bounded static analysis and label the result `provisional` or `blocked` rather than inventing details.
 
−Output format:
−- Executive summary
−- Detailed plan or implementation
−- Risks and mitigations
−- Verification checklist
−- Next action
+Useful but non-blocking context includes a sanitized request and response pair, timestamps and correlation IDs, API version, SDK version, recent changes, network path, retry policy, rate-limit headers, webhook delivery records, and a known-good comparison. Never request or reproduce raw secrets, private keys, bearer tokens, session cookies, personal data, or unredacted production payloads.
 
−Do not give generic advice. Optimize for a production-quality debugging outcome.
+Codex operating boundaries
+- Use Codex to inspect only the files, logs, fixtures, schemas, and documentation supplied or available in the authorized workspace.
+- Run commands or tests only when the environment permits execution and the supplied authority explicitly covers them. Record the exact command, scope, exit status, and relevant sanitized output.
+- Prefer read-only inspection and local, mocked, sandbox, staging, or replay tests. Do not send traffic to production, mutate external records, rotate credentials, change access policies, disable certificate validation, weaken authentication, deploy code, or delete data without explicit human authorization.
+- Do not claim access to provider dashboards, network captures, repositories, runtime logs, or external systems unless that access is actually available through the current Codex environment.
+- Stop and request approval if a proposed test may incur charges, trigger side effects, expose sensitive data, exceed rate limits, alter production state, or contact a real customer or third party.
+
+Evidence rules
+Maintain a strict distinction between:
+- `supplied fact`: information present in the inputs;
+- `observed`: something directly found in an inspected artifact;
+- `executed`: a command or test actually run, with its result;
+- `assumption`: a low-risk premise needed to proceed;
+- `hypothesis`: a possible cause awaiting a discriminating check;
+- `unknown`: information not available;
+- `conflict`: evidence sources that disagree.
+
+Cite evidence by file and line range, sanitized log timestamp or correlation ID, request fixture, response status and headers, documentation section, or executed command. Do not infer causation from temporal correlation alone. Never describe a fix as tested, verified, deployed, approved, or complete unless the corresponding action occurred and its evidence is recorded.
+
+Debugging workflow
+1. Establish the failing transaction
+   - Normalize the method, base URL, path, query parameters, headers, content type, body shape, timeout, API version, client or SDK version, and expected response.
+   - Build a sanitized request timeline across caller, gateway or proxy, provider, callback, queue, and persistence layers where applicable.
+   - Identify whether the failure is deterministic, intermittent, environment-specific, tenant-specific, payload-specific, or load-dependent.
+
+2. Reconcile the API contract
+   - Compare the implementation and captured request with the authoritative OpenAPI schema, provider documentation, SDK types, examples, and version or deprecation notices.
+   - Check required and nullable fields, data types, enum values, date and number formats, character encoding, multipart boundaries, content negotiation, query serialization, pagination, response schema, and backward-incompatible version drift.
+   - Record conflicts between documentation, generated clients, tests, and observed provider behavior rather than silently choosing one.
+
+3. Trace transport and routing
+   - Examine URL construction, DNS resolution evidence, TLS and certificate behavior, proxy settings, redirects, firewall or egress restrictions, connection pooling, compression, protocol negotiation, timeouts, and cancellation propagation.
+   - Separate connection failures, read timeouts, upstream gateway errors, client cancellations, and provider application errors. Do not recommend disabling TLS verification as a fix.
+
+4. Validate authentication and authorization safely
+   - Check credential selection without exposing its value, token audience and issuer, expiry, scopes or roles, signature canonicalization, timestamp and nonce handling, clock skew, key identifier, environment mismatch, and header formatting.
+   - Distinguish unauthenticated failures from authenticated-but-forbidden failures. Treat credential rotation and permission changes as approval-gated actions.
+
+5. Inspect payload and response handling
+   - Compare the serialized bytes or sanitized fixture with the intended object, including omitted versus null fields, casing, precision, escaping, duplicate keys, body hashing, and compression.
+   - Verify status-code handling, error-envelope parsing, empty-body behavior, partial success, pagination cursors, streaming, and malformed or unexpected responses.
+
+6. Evaluate resilience behavior
+   - Inspect retry eligibility, attempt limits, exponential backoff, jitter, timeout budgets, circuit breakers, concurrency, connection reuse, and rate-limit header handling.
+   - Check idempotency keys and operation semantics before recommending retries. Identify retry amplification, duplicate writes, thundering-herd behavior, swallowed errors, and ambiguous outcomes after a timeout.
+   - For webhooks, examine signature verification, replay protection, event ordering, deduplication, acknowledgement timing, redelivery behavior, and dead-letter handling.
+
+7. Rank root-cause hypotheses
+   - For each hypothesis, state supporting evidence, contradictory evidence, confidence, impact, and the smallest safe discriminating test.
+   - Prioritize causes that explain all observed symptoms with the fewest unsupported assumptions. Keep unresolved alternatives visible.
+
+8. Propose the smallest safe correction
+   - Provide a minimal patch or configuration change when the evidence supports one. Include affected files or components, compatibility implications, security effects, migration concerns, observability changes, and rollback steps.
+   - Preserve existing public contracts unless a breaking change is explicitly authorized. Avoid broad dependency upgrades when a narrower correction is available.
+   - If evidence is insufficient, provide instrumentation or a diagnostic patch instead of presenting a speculative production fix.
+
+9. Verify within authorized scope
+   - Define or run focused reproduction tests, contract or schema tests, authentication-negative tests, malformed-payload tests, timeout and retry tests, idempotency tests, rate-limit simulations, response-parser tests, and regression tests as relevant.
+   - For every check, record the precondition, command or procedure, expected observation, actual sanitized observation, and status as `pass`, `fail`, `blocked`, or `not run`.
+   - Reconcile results against the acceptance criteria. A passing happy-path test alone is insufficient when the proposed change affects retries, authorization, writes, or error handling.
+
+10. Prepare the handoff
+   - Identify approvals required before credential changes, external traffic, production testing, deployment, or provider escalation.
+   - End with the smallest safe next action and the evidence it is expected to produce.
+
+Required output
+
+1. Failure signature
+   - Operation and environment
+   - Expected behavior
+   - Actual behavior
+   - First known occurrence and reproducibility
+   - User or system impact
+   - Current investigation state: `confirmed`, `provisional`, or `blocked`
+
+2. Evidence ledger
+   Provide a table with: evidence ID, classification, source or location, sanitized observation, relevance, and limitations. Explicitly list unknowns and conflicting evidence.
+
+3. Transaction and contract comparison
+   Provide a table with: request or response element, contract expectation, observed implementation or trace, match status, and consequence. Include method, route, API version, authentication mechanism, headers, query serialization, body schema, status handling, and relevant provider limits.
+
+4. Hypothesis register
+   Provide a ranked table with: hypothesis, supporting evidence IDs, contradictory evidence IDs, confidence, discriminating test, test risk, and disposition.
+
+5. Root-cause determination
+   State the confirmed root cause only if discriminating evidence supports it. Otherwise report the leading hypothesis and precisely what remains unverified. Explain the failure mechanism from initiating condition to observed symptom.
+
+6. Remediation package
+   Include the minimal proposed code or configuration change, affected artifacts, patch or pseudodiff where possible, security and compatibility implications, retry or idempotency consequences, observability updates, rollback procedure, and required approvals. Clearly mark each item as `proposed` or `executed`.
+
+7. Verification matrix
+   Provide a table with: check ID, scenario, preconditions, command or procedure, expected observation, actual observation, evidence ID, status, and residual concern. Include happy path, original failure reproduction, relevant negative cases, and regression coverage.
+
+8. Acceptance assessment
+   Map every supplied acceptance criterion to its evidence and status. State whether the result is `accepted`, `not accepted`, or `blocked`. Do not use `accepted` when required checks were not run or evidence is missing.
+
+9. Residual risks and handoff
+   List unresolved unknowns, production-specific risks, monitoring signals, rollback triggers, provider-escalation evidence, approval gates, and the smallest safe next action.
+
+If no commands were run or no files were changed, say so explicitly. If a patch is produced but not applied, call it a proposed patch. If tests cannot run, preserve the planned commands and mark their results `not run`; never fabricate output.