API Troubleshooting

Overview

This playbook covers request failures, bad payloads, wrong methods, and response-shape mismatches.

Why It Matters

API issues often appear as frontend bugs, but the real failure is usually at the request boundary.

Core Concepts

• Check method, URL, headers, payload, and response together.
• Compare the request to the contract.
• Validate the boundary before changing UI code.

Mental Models

The network tab is the shortest path to truth for API problems.

Best Practices

• Reproduce in the browser or curl.
• Inspect status and payload.
• Check auth and caching behavior.

Common Mistakes

• Guessing from the UI alone.
• Ignoring a 2xx response with bad data.
• Forgetting the backend can be correct while the mapping is wrong.

Trade-offs

Troubleshooting at the boundary is usually faster than reading frontend and backend code at the same time.

Decision Framework

Examples

• A 422 usually means validation mismatch.
• A 200 with broken UI usually means mapping or rendering.

Checklists

• Do I know the exact request?
• Did I inspect the response body?
• Is the issue in the request, response, or mapping?

Senior Engineer Notes

Senior engineers use the API boundary to narrow the search quickly. That is usually the fastest route to the fix.

Further Reading

• API Integration
• HTTP
• Debugging