API Integration Debugging Prompt

Debug the API integration described below using Codex and produce an evidence-backed diagnosis, a safe remediation proposal, and concrete verification results.

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]

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.

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.

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.