Client error codes
- 400 The request is malformed, such as if the body does not parse
- 401 Unauthenticated. When no or invalid authentication details are provided. Also useful to trigger an auth popup if the API is used from a browser
- 403 User is unauthorized
- 404 Not Found - When a non-existent resource is requested
- 405 When an HTTP method is being requested that isn't allowed for the authenticated user.
- 409 Resource Conflict can be possible in complex systems. It can be caused by fulfilling the request. Duplicate entries, deleting root objects when cascade-delete not supported are a couple of examples.
- 410 Gone - Indicates that the resource at this end point is no longer available. Useful as a blanket response for old API versions
- 415 Unsupported Media Type - If incorrect content type was provided as part of the request
- 422 Unprocessable Entity - Used for validation errors
- 429 Too Many Requests - When a request is rejected due to rate limiting
Server Error Codes
- 500 INTERNAL SERVER ERROR – The general catch-all error when the server-side throws an exception
- 501, Not Implemented. The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource
- 503 Service Unavailable. The server is currently unable to handle the request due to a temporary overloading or maintenance of the serve
Commonly used HTTP Codes
Operation | HTTP Verb | Response |
Update a resource | PUT | 200 (OK), with data |
Creation of new resource | POST | 201 upon successful creation, returning a Location header with a link to the newly created resource |
Read | Get | 200 (OK), with data 200 (OK) with empty list - if response is supposed to return collection and has empty data set 404 when specific resource doesn't exist |
Deleting a resource | Delete | 204 (NO CONTENT) 404 (NOT FOUND) when calling DELETE on a resource a second time |