Step by step
Capture the complete exchange safely
Record timestamp, environment, method, path, status code, response body and a request correlation ID. Redact tokens, cookies and personal data.
Classify the failure
Separate DNS or TLS, connection, authentication, permission, validation, rate limit, server error and client parsing problems.
Reproduce the smallest request
Use a known account and minimal payload in a non-production environment where possible. Compare a working request field by field.
Confirm the contract
Check current API documentation, content type, required headers, date formats, pagination and version. Treat retries carefully for non-idempotent operations.
Ready-to-use checklist
- Secrets redacted
- Status and response captured
- Environment identified
- Minimal reproduction built
- Working request compared
- Retry safety considered
Common problems
The server returns only a generic 500
Use correlation IDs and server logs; do not repeatedly change the client when the failure is clearly after request acceptance.
The same token works elsewhere
Compare audience, scopes, environment, account permissions, clock skew and resource ownership.