HTTP status code reference for CICS Web support
For full information about the meaning and correct use of status codes, you should consult the HTTP specification to which you are working.
This topic provides a brief summary of the HTTP/1.1 status codes as they relate to CICS Web support. When you are selecting status codes to be sent through the Web error programs, or directly from a user application, it is important to check the HTTP specification to which you are working. The HTTP specification provides detailed guidance and requirements about how you should use status codes, such as what should be the content of the response body, and what HTTP headers should be included.
Status codes for responses sent by CICS (when CICS is an HTTP server)
- CICS Web support generates a response to a Web client in the following circumstances:
- When CICS Web support detects a problem in initial processing of a request from a Web client; for example, if required information is missing from the request, or if the request is sent too slowly and the receive timeout is reached.
- When the analyzer specified for the TCPIPSERVICE definition is unable to process the request and passes control to a Web error program.
- When neither the analyzer nor the converter program processing, manages to determine what application program should be executed to service the request.
- When an abend occurs in the analyzer program, converter program, or user-written application program. This ensures that a response can be returned to the Web client even though processing has failed.
In these situations, CICS selects an appropriate status code and creates a default error response. Table xx describes the status codes used by CICS for these purposes. Note that CICS does not generate a response in situations where the user-written application program has completed processing successfully and wants to return a response indicating an error; for example, where the client has specified a method not supported for the resource. The user-written application creates the response in this case.
- For most CICS-generated responses with 4xx and 5xx status codes, the response sent to the Web client can be modified by tailoring the user-replaceable Web error program DFHWBEP. CICS-generated responses involving 1xx, 2xx and 3xx status codes cannot be modified. The Web error programs can change the status code, reason phrase, HTTP headers and message body for the response. When you modify the Web error programs, ensure that your selection of status code and response content is made according to the requirements in the HTTP specification to which you are working. The CICS Internet Guide, section “Web error program,” explains how to tailor the Web error programs.
- A user application program that responds to a client's request needs to select a suitable status code for the response. The status code can convey the following messages to a Web client:
- The request has completed as expected.
- There is an error that prevents fulfillment of the request.
- The client needs to do something else in order to complete its request successfully. This could involve following a redirection URL, or amending the request so that it is acceptable to the server.
The status code influences the other content of the response, that is, the message body and HTTP headers.
CICS as an HTTP server: Status codes that CICS provides to Web clients
Table 1 shows the status codes used in situations in which CICS provides a response to a Web client's request. Some of these responses can be tailored by modifying the Web error programs. A user application program may also use many of the status codes listed here. Some status codes are only appropriate for HTTP/1.1 clients. CICS does not return these status codes to HTTP/1.0 clients.
Status code and reason phrase provided | Sent to HTTP/1.0 clients? | Situation(s) in which this response is provided | Can be modified in Web error program? |
---|---|---|---|
100 Continue | No | Web client sent an Expect header. | No |
200 OK | Yes | Delivery of normal response. | No |
400 Bad Request | Yes | Syntax error in request (such as request line wrongly specified, request incomplete) OR Host header is not supplied (HTTP/1.1 only). | Yes |
404 Not Found (some situations: Program Not Found, File Not Found) | Yes | The program specified to respond to the request is not found. | Yes |
408 Request Timeout | No | Receive timeout for request has been exceeded. This is determined by the SOCKETCLOSE attribute in the TCPIPSERVICE definition for the port. | Yes |
412 Precondition Failed | No | If-Unmodified-Since header was used on request. | Yes |
417 Expectation Failed | No | Expect header received which did not have value"100-continue". | No |
500 Internal Server Error | Yes | Abend in one of the programs involved with processing the request and providing the response | Yes |
501 Method Not Implemented | Yes | Method is not supported by CICS for this HTTP version.(Includes methods that are supported but not in the way the client requests, such as OPTIONS requests that cite a specific resource.) OR Media type for request is "multipart/byteranges",which is not supported. OR Transfer coding for request is other than "chunked". (Note: Connection is closed by CICS.) | Yes |
505 Version Not Supported | No | HTTP version is higher than 1.1, and method is not recognized for highest version supported by CICS. | Yes |
CICS as an HTTP server: Status codes in user applications
Table 2 shows each status code, describes its relevance for a user application, and suggests appropriate actions, in accordance with the recommendations in the HTTP/1.1 specification. Remember that CICS does not take any specific action that might be implied by these status codes, and that CICS does not generally check their validity against the content of the message. You should ensure that the status codes are correct and that you have taken any necessary action. Ensure that you check the HTTP specification to which you are working, for further information and requirements that apply to each status code.
Status code and usual reason phrase | Suitable for HTTP/1.0 client? | Situation(s) in which you might provide this response | Effect on message body and HTTP headers (where status code is appropriate for a user application). See HTTP specification for more information. |
---|---|---|---|
100 Continue | No | Do not use. CICS handles Expect requests and sends 100-Continue response itself. | |
101 Switching Protocols | No | Do not use. CICS does not support upgrades in HTTP version or security protocol. | |
200 OK | Yes | You have fulfilled the request. A normal response. | Provide normal response body. |
201 Created | Yes | You have created a new resource. (Use 202 Accepted if the resource has not yet been created.) | Message body content and one or more headers required. |
202 Accepted | Yes | You have accepted the request but have not yet processed it, and do not guarantee to process it. | Message body content required. |
203 Non-Authoritative Information | No | Do not use. The headers that you supply will give authoritative information. | |
204 No Content | Yes | You are not sending a message body, perhaps because you only need to send updated headers. | No message body permitted. |
205 Reset Content | No | You want the client to clear the form that initiated the request. | No message body permitted. |
206 Partial Content | No | You support byte range requests, and this response fulfills the request. | Normal response body. One or more headers required. |
300 Multiple Choices | Yes | You are able to provide more than one version of the resource (for example, documents in different languages). | Message body content and one or more headers required. |
303 See Other | No | You want client to make a GET request for another resource that gives a response (in particular, a response about the out come of a POST request). | Message body content and one or more headers required. |
304 Not Modified | Yes | The client made a conditional request, and the resource you are providing has not changed. Note that a response that is built dynamically by an application is likely to be modified on every request. | No message body permitted. One or more headers required. |
400 Bad Request | Yes | The client's request contains syntax errors or similar problems, and you cannot process it. | Message body content required. |
403 Forbidden | Yes | You are refusing the client's request. | Message body content required. |
404 Not Found | Yes | You do not have a resource to respond to the request; or you want to refuse the request without explanation; or no other status code is relevant | Message body content required. |
405 Method Not Allowed | No | The client used a method which is not supported for this resource. | Message body content and one or more headers required. |
406 Not Acceptable | No | The client made a conditional request using Accept headers, but you do not have a version of the resource that meets their criteria. Note that as an alternative to using this status code, you can send a response which does not meet the conditions. | Message body content required. |
408 Request Timeout | No | Not recommended for issuing by user application. Timeout should be specified for handling by CICS Web support using the SOCKETCLOSE attribute on the TCPIPSERVICE definition. | |
409 Conflict | No | The resource has been changed and the client's request cannot be applied to the resource as it now stands. | Message body content required. |
410 Gone | No | The resource is permanently unavailable. | Message body content required. |
411 Length Required | No | Do not use. CICS requires HTTP/1.1 requests to specify the Content-Length header for successful socket receive. | |
412 Precondition Failed | No | The client made a conditional request and the conditions were not met. | Message body content required. |
413 Request Entity Too Large | No | Not recommended for issuing by user application. Request size limit should be specified for handling by CICS Web support using the MAXDATALEN attribute on the TCPIPSERVICE definition. | |
414 Request URI Too Long | No | The client's request URL is too large for your application to process. | Message body content required. |
415 Unsupported Media Type | No | The message body sent by the client has a media type or content coding that you do not support | Message body content required. |
416 Requested Range Not Satisfiable | No | The client made a request using the Range header field (but not the If-Range header field), and although you support byte-ranges, that range was not present in the resource. | Message body content and one or more headers required. |
417 Expectation Failed | No | Do not use. CICS handles Expect requests. | |
500 Internal Server Error | Yes | You cannot handle the request because of an application or system error. | Message body content required. |
501 Not Implemented | Yes | The method for the client's request is not supported. This status code should only be issued where the client is HTTP/1.0, or you are using the USER protocol. For the HTTP protocol, during initial processing, CICS rejects any requests with methods that are not recognized. If the method is recognized but does not apply for the resource, 405 Method Not Allowed should be used for HTTP/1.1 clients. | Message body content required. |
503 Service Unavailable | Yes | A user application is unlikely to be in a relevant situation to use this status code, unless it needs to access another application or system which is temporarily unavailable. | Message body content and one or more headers required. |
505 HTTP Version Not Supported | No | Do not use. CICS matches HTTP version of response to HTTP version of client's request. |