HTTP status code reference for CICS Web support

HTTP status codes are provided to clients by a server, to explain the consequence of the client's request. When CICS is an HTTP server, depending on the circumstances, either CICS Web support or the user application program selects an appropriate status code for each response.

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.

Table 1. Status Codes for CICS-generated responses sent to Web 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.

Table 2. Status codes for user-written responses sent to Web clients
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.