Common API Error Codes and How to Fix Them

The errors you'll hit building and consuming APIs, what causes them, and how to debug them.

Every developer building APIs hits the same errors. Here's a field guide to the ones you'll see most, with practical debugging steps for each.

400 Bad Request

What causes it: Malformed JSON (missing comma, trailing comma, unquoted keys), missing required fields, wrong data types, invalid enum values.

How to debug: Check the response body first - a good API tells you exactly which field is wrong. Validate your JSON in a linter. Check for invisible characters copied from rich text editors. Verify Content-Type is application/json.

How to fix: Parse the error message. Fix the payload. If you're building the API, return specific field-level errors in your response body.

401 Unauthorized

What causes it: Expired access token, wrong API key, missing Authorization header, incorrect header format (forgetting "Bearer " prefix), using the wrong environment's credentials.

How to debug: Check that the header exists and is formatted correctly: Authorization: Bearer your-token-here. Decode your JWT and check the expiry (exp claim). Verify you're using the right credentials for the right environment.

How to fix: Refresh the token, fix the header format, or swap in the correct credentials. Implement automatic token refresh in your client code.

403 Forbidden

What causes it: Your authenticated user lacks permission for this action. Insufficient OAuth scopes. CORS blocking your request. IP restrictions.

How to debug: Check the user's role or permissions. Verify your OAuth token has the necessary scopes. If it's CORS, look at the browser console for the specific CORS error and check your server's Access-Control-Allow-Origin header.

How to fix: Request the right scopes, adjust user permissions, or fix your CORS configuration on the server.

404 Not Found

What causes it: Typo in the URL, resource was deleted, wrong API version in the path, trailing slash mismatch.

How to debug: Double-check the URL against the docs. Test with a known-good resource ID. Check if the API treats /users and /users/ differently (some do).

How to fix: Fix the URL. If the resource was deleted, handle that case in your code. Normalize trailing slashes.

405 Method Not Allowed

What causes it: Sending GET when the endpoint expects POST, or vice versa. Common after copy-pasting curl commands or switching between REST and form endpoints.

How to debug: Check the Allow header in the response - it lists the supported methods. Compare with the docs.

How to fix: Use the correct HTTP method. If you're building the API, include the Allow header in your 405 responses.

422 Unprocessable Content

What causes it: The JSON is valid, but the data doesn't pass business logic validation. End date before start date, negative prices, email format wrong, password too short.

How to debug: Read the response body carefully. Good APIs return field-specific validation errors.

How to fix: Fix the data to match the validation rules. If you're building the API, return structured error responses with field names and human-readable messages.

429 Too Many Requests

What causes it: Rate limiting. You've exceeded the allowed number of requests in a time window.

How to debug: Check Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining headers. These tell you the limits and when you can retry.

How to fix: Implement exponential backoff. Cache responses you request frequently. Batch requests when possible. If you consistently hit limits, contact the API provider about higher tiers.

500 Internal Server Error

What causes it: Unhandled exception on the server. Null reference, division by zero, database query failure, uncaught promise rejection.

How to debug: If you own the API, check server logs. If you don't, try varying your request to isolate what triggers it. A 500 from specific inputs suggests a bug on their end.

How to fix: If it's your API, add error handling. Wrap database calls in try/catch, validate inputs before processing, add null checks. Never expose stack traces to clients.

502 Bad Gateway

What causes it: The reverse proxy (nginx, Cloudflare, AWS ALB) couldn't get a valid response from the upstream server. Origin is down, crashed, or returning malformed responses.

How to debug: Check if the origin server is running. Look at proxy/load balancer logs. Verify the upstream configuration points to the right host and port.

How to fix: Restart the origin server, fix its configuration, or increase proxy timeout values if the origin is just slow.

503 Service Unavailable

What causes it: Server overloaded, in maintenance mode, or a dependency is down (database, cache, external API).

How to debug: Check server health metrics. Look for recent deployments. Check if downstream dependencies are responding.

How to fix: Scale up, fix the dependency, or wait for maintenance to complete. Implement circuit breakers for external dependencies to fail gracefully.