This section is a reference for all codes - each resource operation has information about appropriate response codes. This section also lists generically useful codes (404, 429, 500...).
APIs MUST return HTTP status codes that are most appropriate for the response.
APIs MUST return a standardized exception payload when returning a 4XX-series or 5XX-series response.
APIs SHOULD return one of the following response codes:
| Status Code | When to use |
|---|---|
| 200 - OK | Use for any successful synchronous request. |
| 201 - Created | Use when a new resource is created from either POST or PUT. You should also provide a Location header with the URI to the created resource. The body should include the resource created with a self link. |
| 202 - Accepted | Use sparingly, and only when the response cannot be processed synchronously. The body should provide a URL for the client to retrieve any output of the request at in the future. |
| 204 - No Content | Use when a DELETE request has been invoked successfully. |
| 400 - Bad Request | Use when the data submitted to the request cannot be parsed or is syntactically invalid. |
| 401 - Unauthorized | Use when the user has failed to provide valid credentials. |
| 403 - Forbidden | Use when the user has valid credentials, but does not have permissions to perform the desired request. You should inform the user that they don't have permissions. In some cases, in order to not leak information it may be preferred to use a 404 when a user is forbidden from accessing a specific identified resource. |
| 404 - Not Found | Use when a resource does not exist or cannot be found. Can also be used when a user does not have access to a specific resource, but you do not want to leak its existence to the client. |
| 409 - Conflict | When PUTing or PATCHing a resource, and the version you provide is not the most recent version, this indicates a conflict with multiple updates on the same resource |
| 412 - Precondition Failed | When PUTing or PATCHing a resource, and the If-Match value you provide is not the current ETag, this indicates the client has not seen the most recent version |
| 422 - Unprocessable Entity | Use when the data in the request is valid and parsable, but the values contained within are semantically invalid for the data contract. (E.g. required field omitted, invalid value for enumeration, operation invalid at current state). |
| 429 - Too Many Requests | Use for rate limiting. |
| 500 - Internal Server Error | Use when you have an internal issue with your service that prevents the request from being handled, and for default error handling. |