Tips for using HTTP codes correctly in APIs

Tips for using HTTP codes in the API

1. Don't return 200 for errors

A common mistake is to return 200 OK with body `{ "error": "..." }`. Use the appropriate error codes.

2. Distinguish between 401 and 403

3. Use 201 to create resources

A POST request creating a new resource must return 201 Created with a Location header.

4. Use 204 for empty responses

DELETE and PUT requests without a response body must return 204 No Content.

5. Handle 429 on the client

Implement exponential backoff when receiving 429 Too Many Requests.

6. Use 422 for validation errors

Distinguish between 400 (incorrect syntax) and 422 (correct syntax, but invalid data).

7. Add Retry-After to 503

If the service is temporarily unavailable, indicate how many seconds later the request will be repeated.

8. Document response codes

Each API endpoint must have documentation with all possible response codes.

See also: JWT Decoder, MIME Types, Cron generator