return-appropriate-status-codes.md

Return appropriate status codes

Return appropriate HTTP status codes with each response. Successful responses should be coded according to this guide:

• 200: Request succeeded for a GET call, for a POST, DELETE or PATCH call that completed synchronously, or for a PUT call that synchronously updated an existing resource
• 201: Request succeeded for a POST or a PUT call that synchronously created a new resource. Don't forget the Location header to point to the newly created resource, it is usefull for POST because the target resource is not the created resource.
• 202: Request accepted for a POST, PUT, DELETE, or PATCH call that will be processed asynchronously
• 206: Request succeeded on GET, but only a partial response returned: see above on ranges

Pay attention to the use of authentication and authorization error codes:

• 401 Unauthorized: Request failed because user is not authenticated
• 403 Forbidden: Request failed because user does not have authorization to access a specific resource

Return suitable codes to provide additional information when there are errors:

• 422 Unprocessable Entity: Your request was understood, but contained invalid parameters
• 429 Too Many Requests: You have been rate-limited, retry later
• 500 Internal Server Error: Something went wrong on the server, check status site and/or report the issue

Refer to the HTTP response code spec for guidance on status codes for user error and server error cases.