HTTP Response Status Codes
HTTP response status codes are numerous, and only a few apply to API interactions. This section details relevant HTTP status codes to API consumers and the Profiles that specify their use. The status codes are broken into two sections—Processing and Success Codes and Client Failure Codes.
Processing and Success Codes
| Status Code | Meaning | Profiles | Source |
|---|---|---|---|
100 Continue | The client can send a full request given the headers provided in the first, headers-only request. Used in “look before you leap” operations with large, expensive client payloads. | Preflight | RFC 7231, section 6.2.1 |
200 OK | The request was processed successfully. All HEAD operations return this status code. | All profiles | RFC 7231, section 6.3.1 |
201 Created | Creation request was processed successfully. 201 is the usual response to a POST operation. In Level 3 REST, the body contains no content. A resource may offer the Representation profile to give the client the ability to return content with the response. | Form, Upload | RFC 7231, section 6.3.2 |
202 Accepted | A state modification/creation operation (PUT, POST, PATCH or DELETE) has been accepted for processing but is not complete. The body contains no content. | Async | RFC 7231, section 6.3.3 |
204 No Content | The request was processed successfully, but the body contains no content. This status code is the normal result for DELETE, PATCH and PUT requests. A resource may offer the Representation profile to give the client the ability to return content with the response. | Form, Home, Nexus, Representation | RFC 7231, section 6.3.5 |
206 Partial Content | The request contains a portion of the full content of the resource. | Content | RFC 7233, section 4.1 |
303 See Other | The client should GET the URI found in the location header. | Action, Lookup | RFC 7231, section 6.4.4 |
307 Temporary Redirect | The client should retry their request at the URI found in the location header. The new location is temporary so clients should re-request at the original URI to ensure they have the latest URI. | Alias | RFC 7231, section 6.4.7 |
308 Permanent Redirect | The client should retry their request at the URI found in the location header. The new location is permanent so clients can replace their use of the original URI with the new URI. Often used to migrate API endpoints without breaking older clients. | Alias | RFC 7538 |
Client Failure Codes
Resources reject client requests for various reasons, and the client may be able to attempt their operation again with a corrected request. These status codes give the client information to help them correct their request and try again.
| Status Code | Meaning | Profiles | Source |
|---|---|---|---|
400 Bad Request | Incorrect message formatting. Examples include invalid JSON body and incorrect request parameters in URL and header values. The Client should examine their code and API docs to fix their request code before resubmitting. | All profiles | RFC 7231, section 6.5.1 |
403 Forbidden | Business rule failure. For instance, in a hotel API, a client cannot book a room that is not available. | Action, Data, Form | RFC 7231, section 6.5.3 |
404 Not Found | Resource does not exist and thus cannot be found. It may have been deleted via the API or removed by the backend system. | All profiles | RFC 7231, section 6.5.8 |
409 Conflict | Resource state conflict. Used in PATCH responses when the content cannot be patched successfully given the supplied patch body. | Entity | RFC 7231, section 6.5.8 |
411 Length Required | The resource requires the content-length header to process a PUT request. | Content | RFC 7231, section 6.5.10 |
412 Precondition Failed | The request has preconditions that cannot be met, such as a newer last-modified date or the etag has changed. | Entity | RFC 7232, section 4.2 |
413 Payload Too Large | The request payload is too large for the resource to accept. | Content | RFC 7231, section 6.5.11 |
415 Unsupported Media Type | The resource cannot accept the media type defined for the payload. | Content, Data, Form, Lookup | RFC 7231, section 6.5.13 |
416 Range Not Satisfiable | Client requested a range for a representation that cannot be met. For instance, an image representation may have 4k of data, but the range asked for 8k of data. | Content | RFC 7233, section 4.4 |
417 Expectation Failed | The resource does not support the expect header and cannot preflight a request. | Preflight | RFC 7231, section 6.5.14 |
422 Unprocessable Entity | Message format is correct, but the data presents unknown or incorrect semantics. The resource does not understand the message. Missing or incorrect request parameters are included in this category. The client has understood the typing and formatting of the API, but is sending incorrect values. | Content, Data, Form, Lookup | RFC 4918, section 11.2 |
428 Precondition Required | The client did not send the required content-type header in a PATCH request. Examine the accept-patch header of the resource to determine the acceptable patch content types. | Data | RFC 6585, section 3 |