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. When CICS is an HTTP client, most status codes received from the server are passed to the user application program for handling.

Status codes and reason phrases explains how status codes are used in HTTP responses.

For full information about the meaning and correct use of status codes, you should consult the HTTP specification to which you are working. The HTTP protocol has more information about the HTTP specifications.

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 an installed URIMAP definition matches the request, but the URIMAP definition or virtual host is disabled, or the resource for a static response cannot be read.
    • When the matching URIMAP definition refers the request to an ATOMSERVICE resource definition, but the ATOMSERVICE definition is disabled, or the CICS resource for the Atom feed cannot be read.
    • When URIMAP matching fails, and the analyzer specified for the TCPIPSERVICE definition is unable to process the request and passes control to a web error program.
    • When neither the URIMAP definition, nor the analyzer and 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.
    • When a URIMAP specifies a redirection response.
    • When a web client is not authorized to access the resources needed to provide the response.
    In these situations, CICS selects an appropriate status code and creates a default response. Table 1 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 programs DFHWBEP and DFHWBERX. 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. Web error programs 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 fulfilment 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. Sending an HTTP response from CICS as an HTTP server tells you how to assemble and send a response, including a status code and reason phrase.
Status codes for responses received by CICS (when CICS is an HTTP client)
  • When CICS is an HTTP client, CICS web support passes responses with most status codes directly to the user application program for handling. A small number of status codes are handled by CICS and are not returned to the application. If a status code is passed to the application, this indicates that CICS has not taken any action in response to the code, and it is the application's responsibility to check the code and take appropriate action.
  • You should design your user application to act appropriately when it receives a message with a status code indicating an error. In particular, you should always check the status code in the following circumstances:
    • If you intend to make an identical request to the server, now or during a future connection.
    • If you intend to make further requests to the server using this connection.
    • If your application is carrying out any further processing that depends on the information you receive in the response.
    Check the HTTP specification to which you are working for guidance on what action is appropriate. The HTTP/1.1 specification contains no MUST level requirements that demand further action from the application on receiving a status code, but there are some SHOULD requirements, such as the requirement to follow a redirection.

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. CICS as an HTTP server: 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
201 Created Yes A new object has been created. No
301 Moved Permanently Yes URIMAP definition specifies a redirection, with attribute REDIRECTTYPE (PERMANENT). No
302 Found Yes URIMAP definition specifies a redirection, with attribute REDIRECTTYPE (TEMPORARY). No
304 Not Modified Yes If-Modified-Since header was used on request, and CICS is able to verify that the static response has not been modified. Yes
400 Bad Request (some situations: Invalid Request) Yes Syntax error in request (such as request line wrongly specified, request incomplete, problem in Atom entry for Atom POST or PUT request). OR Host header is not supplied (HTTP/1.1 only). OR A PUT request without an If-Match header was received. A client that wants to update an object without knowing the current entity tag should specify If-Match: *. Yes
401 Basic Authentication Error Yes User ID and password required for basic authentication. This is determined by security settings for the TCPIPSERVICE definition for the port. Yes
403 Forbidden (some situations: Client Authentication Error) Yes Basic authentication was not successful. OR There is a problem with the client certificate. OR User is not authorized to access a resource that is needed to provide the response, such as an ATOMSERVICE resource definition, alias transaction, CICS command used by a program, or CICS resource containing response data. Yes
404 Not Found (some situations: Program Not Found, File Not Found) Yes The program specified to respond to the request is not found. OR A resource that is needed to provide the response is not found. OR A record is not found within a CICS resource that is used to provide data for an Atom feed.OR An image file 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
409 Conflict (some situations: Duplicate resource) Yes An existing object already exists with the specified URL, so the new object is not created. No
412 Precondition Failed Yes If-Unmodified-Since header was used on request. OR The entity tag value on the If-Match header does not match the entity tag for the object being updated. Yes
417 Expectation Failed No Expect header received which did not have value "100-continue". No
500 Internal Server Error (some situations: Resource Error) Yes Abend in one of the programs involved with processing the request and providing the response. OR Error reading z/OS® UNIX file for a static response.OR Error involving a resource for an Atom feed, such as an error producing XML markup from a resource record for use as Atom entry content. 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
503 Service Unavailable Yes A matching URIMAP definition exists, but either it is disabled, or the virtual host of which it is a part is disabled. OR A matching URIMAP definition references an ATOMSERVICE resource definition that is disabled.OR The resource specified in the URIMAP definition or ATOMSERVICE definition for providing response data is disabled. 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. CICS as an HTTP server: 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 fulfils 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.
301 Moved Permanently Yes Not recommended for issuing by user application. Redirection can be managed using the LOCATION and REDIRECTTYPE attributes in the URIMAP definition, so that CICS generates a correct response without calling an application program. REDIRECTTYPE (PERMANENT) selects this status code.  
302 Found Yes Not recommended for issuing by user application. When you use a URIMAP definition for redirection, REDIRECTTYPE (TEMPORARY) selects this status code.  
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 outcome 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. For resources that do not change, consider delivering a static response using a URIMAP definition. No message body permitted. (You can use the DOCTOKEN option to specify a document with no content.) One or more headers required.
305 Use Proxy No You want client to go through a named proxy for its request. One or more headers required.
307 Temporary Redirect No Not recommended for issuing by user application. CICS uses the 302 status code, rather than this status code, for URIMAP redirection.  
400 Bad Request Yes The client's request contains syntax errors or similar problems, and you cannot process it. Message body content required.
401 Unauthorized Yes Do not use. CICS handles basic authentication process when this is specified in the security settings for the TCPIPSERVICE definition.  
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 that 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.
407 Proxy Authentication Required No Do not use. CICS does not act as a proxy server.  
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.
502 Bad Gateway Yes Do not use. CICS does not act as a proxy or gateway.  
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.
504 Gateway Timeout No Do not use. CICS does not act as a proxy or gateway.  
505 HTTP Version Not Supported No Do not use. CICS matches HTTP version of response to HTTP version of client's request.  

CICS as an HTTP client: Handling status codes received on responses from servers

Table 3 shows the status codes that you might receive on a response from a server, and suggests appropriate actions, in accordance with the recommendations in the HTTP/1.1 specification. The WEB RECEIVE command returns the status code and status text. Bear in mind that the server might have changed the text of the reason phrase from the text that is suggested in the HTTP specification.

Ensure that you check the HTTP specification to which you are working, for further information and requirements that apply to each status code.

Table 3. CICS as an HTTP client: Handling status codes on responses
Status code and probable reason phrase Why would the server send this status code? Suggested action by user application program
100 Continue You used the ACTION(EXPECT) option on the WEB SEND command, and the server accepts the full message send. CICS handles this response by sending message body. User application will not receive this status code.
101 Switching Protocols Should not be used. Protocol upgrading is not supported by CICS web support. User application should not receive this status code.
200 OK Request is successful. A normal response. Continue processing the response as planned.
201 Created You requested creation of a resource and this has been done. Continue processing the response as planned.
202 Accepted Server accepts your request but processing has not yet been carried out. Continue processing the response as planned, but note that any changes you made have not necessarily been committed, and might never be committed.
203 Non-Authoritative Information Headers relating to message body are not an exact match with those on the server. Continue processing the response as planned.
204 No Content There is no message body for the response. Continue processing the response as planned, but note that there is no body to receive.
205 Reset Content Server wants you to clear the form that caused the request to be sent. Clear any form fields that you were using to make the request.
206 Partial Content You made a request using the Range header field and it was successful. Continue processing the response as planned.
300 Multiple Choices Different versions of the resource are available. Choose your preferred version from the information provided, and make a new request. There might be a Location header containing the URL for the server's preferred choice.
301 Moved Permanently The resource has moved permanently to a new location. Make a new request to the URL supplied by the server (probably in the Location header), and use this for all future requests.
302 Found The resource has moved temporarily to a new location. Make a new request to the URL supplied by the server (probably in the Location header), but do not use this for future requests.
303 See Other Server wants you to make a GET request for another resource that gives a response (in particular, a response about the outcome of a POST request). Make a new request, using the GET method, to the URL supplied by the server (probably in the Location header).
304 Not Modified You made a conditional request and the resource has not changed. Refer to your existing stored version of the response for the information, but do not present this to a user as current information, because CICS does not support caching.
305 Use Proxy Server wants you to use the specified proxy for your request. Make a new request using the URL supplied by the server (in the Location header).
307 Temporary Redirect As for 302 Found. As for 302 Found.
400 Bad Request Something is wrong with the syntax of your request. Check the request, make changes and try again.
401 Unauthorized Server requires authorization; or your supplied authorization has been refused. See CICS as an HTTP client: authentication and identification.
403 Forbidden Server refuses your request. Do not repeat the request. Message body might contain information about why the request was refused.
404 Not Found Server has not found the requested URL. Check that the request was specified as you intended. The situation might be temporary, so consider trying again later.
405 Method Not Allowed You specified a method which is not supported for this resource. Read the Allow header in the response for a list of supported methods, and make a new request using one of these methods, if wanted.
406 Not Acceptable You made a request using Accept headers, and the server does not have a version of the resource that meets your criteria. Examine the message body for information about resources that the server does have, and make a new request for one of these, if wanted.
407 Proxy Authentication Required A proxy server requires authorization; or your supplied authorization has been refused. See CICS as an HTTP client: authentication and identification.
408 Request Timeout Server will not wait any longer for you to complete your request. Repeat the request, if wanted. Check that your application is not taking a long time to assemble and send the message.
409 Conflict The resource has been changed and your request cannot be applied to the resource as it now stands. Examine the message body for information about the cause of the conflict, and make a new request based on this information, if wanted.
410 Gone The resource is permanently unavailable. Do not repeat the request in the future.
411 Length Required Server requires you to supply a Content-Length header. CICS normally provides that header, unless you are using the USER protocol on the TCPIPSERVICE definition. If that is the case, write the header yourself and make a new request.
412 Precondition Failed You made a conditional request and the conditions were not met. Continue processing as planned, noting that any action specified in your request has not been applied.
413 Request Entity Too Large Your message body is too large for the server to process. Read the Retry-After header to see if the situation is temporary. You may wait, or reduce the length of the message body, and try again. You might need to open a new connection.
414 Request URI Too Long Your request URL is too long for the server to process. Check the request and try again, or abandon the request.
415 Unsupported Media Type You sent a message body with a media type or content coding that the server does not support for this resource. Check the media type that you have specified, and correct and repeat the request if you have made an error.
416 Requested Range Not Satisfiable You made a request using the Range header field, but that range was not present in the resource. Read the Content-Range header to see the actual length of the resource, and repeat the request with an appropriate byte range, if wanted.
417 Expectation Failed You used the ACTION (EXPECT) option on the WEB SEND command, but the server does not accept the full message send. You may repeat the same request without the ACTION (EXPECT) option, but it will be likely to fail again. Check the request is correctly specified, and correct and repeat the request if you have made an error.
500 Internal Server Error Server cannot handle the request because of an unexpected error. The situation might be temporary, so consider trying the request again later.
501 Not Implemented Server does not support this request method. Do not repeat the request.
502 Bad Gateway Your request has gone through a proxy or gateway, which has received an invalid response from another server. The situation might be temporary, so consider trying the request again later, perhaps avoiding the proxy or gateway if possible.
503 Service Unavailable Server is temporarily unable to handle the request. Read the Retry-After header to see if the condition is temporary, and if it is, try again after that time.
504 Gateway Timeout Your request has gone through a proxy or gateway, which did not receive a timely response from another server. Repeat the request if wanted, perhaps avoiding the proxy or gateway if possible.
505 HTTP Version Not Supported Should not be used. CICS web support sends client requests with HTTP/1.1 as version. User application should not receive this status code.

dfhtl_statusref.html | Timestamp icon Last updated: Thursday, 27 June 2019