HTTP response code reference

REST APIs use HTTP status codes to relay the results from an API operation. Status codes are primarily useful for detecting REST API errors, and by specifying your own response codes you can diagnose those errors more efficiently.

HTTP status codes are divided into classes according to the leading digit of the status code. The following table summarizes the HTTP status codes supported by the z/OS® Connect API toolkit, and common practices in implementation.

Class	Description
2xx Success	The user request was successfully received, accepted, and processed.
3xx Redirection	Indicates that the user must take additional action to complete the request.
4xx Client Error	The user request was not fulfilled due to malformed request syntax or other client issues.
5xx Server Error	The user request appeared valid, but was not fulfilled due to an issue with the server.

Note: The z/OS Connect API toolkit supports user-created response codes. To create your own response code, specify a numeric value in the range of 100 to 599 within the Add Response window of the API editor.

Restriction: The z/OS Connect API toolkit does not support the specification of 1xx class response codes.

The following list demonstrates how HTTP status codes are commonly used in REST APIs. Use this list to determine which status codes are suitable to implement into your API operation responses.

200 (OK): The REST API accepted and fulfilled the user request.
201 (Created): The REST API accepted the user request, and created a resource inside of a collection.
You can reference the newly created resource in the response message URI path using HTTP-to-JSON mapping.
202 (Accepted): The REST API has accepted the user request. A 202 response is typically used for requests which either take a long time to process, or for requests that are not guaranteed to be fulfilled.
The current status of the user's request can be returned in the response message URI path using HTTP-to-JSON mapping.
204 (No Content): The REST API has successfully completed the user request and is not returning a status message.
The API operation was successful, but no information is returned in the response body. A 204 response does not have a message body. If the client sending the HTTP request is a user agent, the 204 response should not change the user's document view.
300 (Multiple Choices): The requested resource has multiple options, or there are multiple versions of the requested resource.
301 (Moved Permanently): The REST API resource model has been changed, the requested resource has been assigned a new URI.
302 (Found): The requested resource has been either moved temporarily, or may be requested by using a different HTTP request.
304 (Not Modified): A 304 status code informs the user that the requested resource has not been modified since the date specified in the If-Modified-Since field.
400 (Bad Request): The REST API either cannot process the user request due to a client error or malformed request syntax.
401 (Unauthorized): The user request requires authentication. If authentication credentials were provided, access has not been granted to the requested resource.
403 (Forbidden): The user request is valid, but the REST API refuses to process the request.
A 403 status code differs from a 401 status code, and should not be used interchangeably. A 403 status code typically indicates that permission is required for the requested resource, a 401 status code informs the user that valid authentication credentials are required for the requested resource.
404 (Not Found): The requested resource cannot be located. The REST API either cannot map the user request URI to a resource, or the resource is no longer available.
410 (Gone): The requested resource is no longer available. This status code should only be issued it is certain that the requested resource has been permanently removed.
500 (Internal Server Error): The REST API encountered an unexpected condition. This generic error response may be issued when a more specific status code is not suitable.
501 (Not Implemented): The REST API does not support the functionality specified in the user request.
503 (Service Unavailable): A 503 status code is issued when the REST API service is unavailable. Generally this indicates that the service could be down for maintenance, has crashed, or is temporarily unable to handle the user request.
550 (Permission Denied): The REST API accepts the user request as valid, but did not process. The user does not have the necessary permissions to make the request.