UNPKG

@readme/oas-examples

Version:

A collection of example OpenAPI 3.x and Swagger 2.0 documents.

932 lines (931 loc) 32.2 kB
openapi: 3.0.3 info: version: 1.0.0 title: HTTP Status Codes description: Demos how we handle various status codes. Documentation pulled from https://developer.mozilla.org/en-US/docs/Web/HTTP/Status servers: - url: https://httpbin.org paths: '/status/200': get: tags: - Successful responses summary: Returns a "200 OK" description: |- The request has succeeded. The meaning of the success depends on the HTTP method: * `GET`: The resource has been fetched and is transmitted in the message body. * `HEAD`: The representation headers are included in the response without any message body. * `PUT` or `POST`: The resource describing the result of the action is transmitted in the message body. * `TRACE`: The message body contains the request message as received by the server. responses: '200': description: OK '/status/201': get: tags: - Successful responses summary: Returns a "201 Created" description: The request has succeeded and a new resource has been created as a result. This is typically the response sent after `POST` requests, or some `PUT` requests. responses: '201': description: Created '/status/202': get: tags: - Successful responses summary: Returns a "202 Accepted" description: The request has been received but not yet acted upon. It is noncommittal, since there is no way in HTTP to later send an asynchronous response indicating the outcome of the request. It is intended for cases where another process or server handles the request, or for batch processing. responses: '202': description: Accepted '/status/203': get: tags: - Successful responses summary: Returns a "203 Non-Authoritative Information" description: This response code means the returned meta-information is not exactly the same as is available from the origin server, but is collected from a local or a third-party copy. This is mostly used for mirrors or backups of another resource. Except for that specific case, the "200 OK" response is preferred to this status. responses: '203': description: Non-Authoritative Information '/status/204': get: tags: - Successful responses summary: Returns a "204 No Content" description: There is no content to send for this request, but the headers may be useful. The user-agent may update its cached headers for this resource with the new ones. responses: '204': description: No Content '/status/205': get: tags: - Successful responses summary: Returns a "205 Reset Content" description: Tells the user-agent to reset the document which sent this request. responses: '205': description: Reset Content '/status/206': get: tags: - Successful responses summary: Returns a "206 Partial Content" description: This response code is used when the [Range](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range) header is sent from the client to request only part of a resource. responses: '206': description: Partial Content '/status/207': get: tags: - Successful responses summary: Returns a "200 Multi-Status" description: Conveys information about multiple resources, for situations where multiple status codes might be appropriate. responses: '207': description: Multi-Status '/status/208': get: tags: - Successful responses summary: Returns a "208 Already Reported" description: Used inside a `<dav:propstat>` response element to avoid repeatedly enumerating the internal members of multiple bindings to the same collection. responses: '208': description: Already Reported '/status/218': get: tags: - Successful responses summary: Returns a "218 This is fine" responses: '218': description: This is fine '/status/226': get: tags: - Successful responses summary: Returns a "226 IM Used" description: The server has fulfilled a GET request for the resource, and the response is a representation of the result of one or more instance-manipulations applied to the current instance. responses: '226': description: IM Used '/status/300': get: tags: - Redirection messages summary: Returns a "300 Multiple Choice" description: The request has more than one possible response. The user-agent or user should choose one of them. (There is no standardized way of choosing one of the responses, but HTML links to the possibilities are recommended so the user can pick.) responses: '300': description: Multiple Choice '/status/301': get: tags: - Redirection messages summary: Returns a "301 Moved Permanently" description: The URL of the requested resource has been changed permanently. The new URL is given in the response. responses: '301': description: Moved Permanently '/status/302': get: tags: - Redirection messages summary: Returns a "302 Found" description: This response code means that the URI of requested resource has been changed temporarily. Further changes in the URI might be made in the future. Therefore, this same URI should be used by the client in future requests. responses: '302': description: Found '/status/303': get: tags: - Redirection messages summary: Returns a "303 See Other" description: The server sent this response to direct the client to get the requested resource at another URI with a GET request. responses: '303': description: See Other '/status/304': get: tags: - Redirection messages summary: Returns a "304 Not Modified" description: This is used for caching purposes. It tells the client that the response has not been modified, so the client can continue to use the same cached version of the response. responses: '304': description: Not Modified '/status/305': get: tags: - Redirection messages summary: Returns a "305 Use Proxy" description: Defined in a previous version of the HTTP specification to indicate that a requested response must be accessed by a proxy. It has been deprecated due to security concerns regarding in-band configuration of a proxy. responses: '305': description: Use Proxy '/status/306': get: tags: - Redirection messages summary: Returns a "306 Switch Proxy" description: This response code is no longer used; it is just reserved. It was used in a previous version of the HTTP/1.1 specification. responses: '306': description: Switch Proxy '/status/307': get: tags: - Redirection messages summary: Returns a "307 Temporary Redirect" description: 'The server sends this response to direct the client to get the requested resource at another URI with same method that was used in the prior request. This has the same semantics as the `302 Found` HTTP response code, with the exception that the user agent must not change the HTTP method used: If a `POST` was used in the first request, a `POST` must be used in the second request.' responses: '307': description: Temporary Redirect '/status/308': get: tags: - Redirection messages summary: Returns a "308 Permanent Redirect" description: 'This means that the resource is now permanently located at another URI, specified by the `Location:` HTTP Response header. This has the same semantics as the `301 Moved Permanently` HTTP response code, with the exception that the user agent must not change the HTTP method used: If a `POST` was used in the first request, a `POST` must be used in the second request.' responses: '308': description: Permanent Redirect '/status/400': get: tags: - Client error responses summary: Returns a "400 Bad Request" description: The server could not understand the request due to invalid syntax. responses: '400': description: Bad Request '/status/401': get: tags: - Client error responses summary: Returns a "401 Unauthorized" description: Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. responses: '401': description: Unauthorized '/status/402': get: tags: - Client error responses summary: Returns a "402 Payment Required" description: This response code is reserved for future use. The initial aim for creating this code was using it for digital payment systems, however this status code is used very rarely and no standard convention exists. responses: '402': description: Payment Required '/status/403': get: tags: - Client error responses summary: Returns a "403 Forbidden" description: The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server. responses: '403': description: Forbidden '/status/404': get: tags: - Client error responses summary: Returns a "404 Not Found" description: The server can not find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 to hide the existence of a resource from an unauthorized client. This response code is probably the most famous one due to its frequent occurrence on the web. responses: '404': description: Not Found '/status/405': get: tags: - Client error responses summary: Returns a "405 Method Not Allowed" description: The request method is known by the server but is not supported by the target resource. For example, an API may forbid DELETE-ing a resource. responses: '405': description: Method Not Allowed '/status/406': get: tags: - Client error responses summary: Returns a "406 Not Acceptable" description: This response is sent when the web server, after performing [server-driven content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation#server-driven_negotiation), doesn't find any content that conforms to the criteria given by the user agent. responses: '406': description: Not Acceptable '/status/407': get: tags: - Client error responses summary: Returns a "407 Proxy Authentication Required" description: This is similar to 401 but authentication is needed to be done by a proxy. responses: '407': description: Proxy Authentication Required '/status/408': get: tags: - Client error responses summary: Returns a "408 Request Timeout" description: This response is sent on an idle connection by some servers, even without any previous request by the client. It means that the server would like to shut down this unused connection. This response is used much more since some browsers, like Chrome, Firefox 27+, or IE9, use HTTP pre-connection mechanisms to speed up surfing. Also note that some servers merely shut down the connection without sending this message. responses: '408': description: Request Timeout '/status/409': get: tags: - Client error responses summary: Returns a "409 Conflict" description: This response is sent when a request conflicts with the current state of the server. responses: '409': description: Conflict '/status/410': get: tags: - Client error responses summary: Returns a "410 Gone" description: This response is sent when the requested content has been permanently deleted from server, with no forwarding address. Clients are expected to remove their caches and links to the resource. The HTTP specification intends this status code to be used for "limited-time, promotional services". APIs should not feel compelled to indicate resources that have been deleted with this status code. responses: '410': description: Gone '/status/411': get: tags: - Client error responses summary: Returns a "411 Length Required" description: Server rejected the request because the `Content-Length` header field is not defined and the server requires it. responses: '411': description: Length Required '/status/412': get: tags: - Client error responses summary: Returns a "412 Precondition Failed" description: The client has indicated preconditions in its headers which the server does not meet. responses: '412': description: Precondition Failed '/status/413': get: tags: - Client error responses summary: Returns a "413 Payload Too Large" description: Request entity is larger than limits defined by server; the server might close the connection or return an `Retry-After` header field. responses: '413': description: Payload Too Large '/status/414': get: tags: - Client error responses summary: Returns a "414 URI Too Long" description: The URI requested by the client is longer than the server is willing to interpret. responses: '414': description: URI Too Long '/status/415': get: tags: - Client error responses summary: Returns a "415 Unsupported Media Type" description: The media format of the requested data is not supported by the server, so the server is rejecting the request. responses: '415': description: Unsupported Media Type '/status/416': get: tags: - Client error responses summary: Returns a "416 Range Not Satisfiable" description: The range specified by the `Range` header field in the request can't be fulfilled; it's possible that the range is outside the size of the target URI's data. responses: '416': description: Range Not Satisfiable '/status/417': get: tags: - Client error responses summary: Returns a "417 Expectation Failed" description: This response code means the expectation indicated by the `Expect` request header field can't be met by the server. responses: '417': description: Expectation Failed '/status/418': get: tags: - Client error responses summary: Returns a "418 I'm a teapot" description: The server refuses the attempt to brew coffee with a teapot. responses: '418': description: I'm a teapot '/status/419': get: tags: - Client error responses summary: Returns a "419 Page Expired" description: '> ⚠️ Unofficial Status Code' responses: '419': description: Page Expired '/status/420': get: tags: - Client error responses summary: Returns a "420 Enhance Your Calm" description: '> ⚠️ Unofficial Status Code' responses: '420': description: Enhance Your Calm '/status/421': get: tags: - Client error responses summary: Returns a "421 Misdirected Request" description: The request was directed at a server that is not able to produce a response. This can be sent by a server that is not configured to produce responses for the combination of scheme and authority that are included in the request URI. responses: '421': description: Misdirected Request '/status/422': get: tags: - Client error responses summary: Returns a "422 Unprocessable Entity" description: The request was well-formed but was unable to be followed due to semantic errors. responses: '422': description: Unprocessable Entity '/status/423': get: tags: - Client error responses summary: Returns a "423 Locked" description: The resource that is being accessed is locked. responses: '423': description: Locked '/status/424': get: tags: - Client error responses summary: Returns a "424 Failed Dependency" description: The request failed due to failure of a previous request. responses: '424': description: Failed Dependency '/status/425': get: tags: - Client error responses summary: Returns a "425 Too Early" description: Indicates that the server is unwilling to risk processing a request that might be replayed. responses: '425': description: Too Early '/status/426': get: tags: - Client error responses summary: Returns a "426 Upgrade Required" description: The server refuses to perform the request using the current protocol but might be willing to do so after the client upgrades to a different protocol. The server sends an [`Upgrade`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Upgrade) header in a 426 response to indicate the required protocol(s). responses: '426': description: Upgrade REquired '/status/428': get: tags: - Client error responses summary: Returns a "428 Precondition Required" description: The origin server requires the request to be conditional. This response is intended to prevent the 'lost update' problem, where a client GETs a resource's state, modifies it, and PUTs it back to the server, when meanwhile a third party has modified the state on the server, leading to a conflict. responses: '428': description: Precondition Required '/status/429': get: tags: - Client error responses summary: Returns a "429 Too Many Requests" description: The user has sent too many requests in a given amount of time ("rate limiting"). responses: '429': description: Too Many Requests '/status/430': get: tags: - Client error responses summary: |- > ⚠️ Unofficial Status Code Returns a "430 Request Header Fields Too Large" description: The server is unwilling to process the request because its header fields are too large. The request may be resubmitted after reducing the size of the request header fields. responses: '430': description: Request Header Fields Too Large '/status/431': get: tags: - Client error responses summary: Returns a "431 Request Header Fields Too Large" description: The server is unwilling to process the request because its header fields are too large. The request may be resubmitted after reducing the size of the request header fields. responses: '431': description: Request Header Fields Too Large '/status/440': get: tags: - Client error responses summary: Returns a "440 Login Time-out" description: '> ⚠️ Unofficial Status Code' responses: '440': description: Login Time-out '/status/444': get: tags: - Client error responses summary: Returns a "444 No Response" description: '> ⚠️ Unofficial Status Code' responses: '444': description: No Response '/status/449': get: tags: - Client error responses summary: Returns a "449 Retry With" description: '> ⚠️ Unofficial Status Code' responses: '449': description: Retry With '/status/450': get: tags: - Client error responses summary: Returns a "450 Blocked by Windows Parental Controls" description: '> ⚠️ Unofficial Status Code' responses: '450': description: Blocked by Windows Parental Controls '/status/451': get: tags: - Client error responses summary: Returns a "451 Unavailable For Legal Reasons" description: The user-agent requested a resource that cannot legally be provided, such as a web page censored by a government. responses: '451': description: Unavailable For Legal Reasons '/status/494': get: tags: - Client error responses summary: Returns a "494 Request Header Too Large" description: '> ⚠️ Unofficial Status Code' responses: '494': description: Request Header Too Large '/status/495': get: tags: - Client error responses summary: Returns a "495 SSL Certificate Error" description: '> ⚠️ Unofficial Status Code' responses: '495': description: SSL Certificate Error '/status/496': get: tags: - Client error responses summary: Returns a "496 SSL Certificate Required" description: '> ⚠️ Unofficial Status Code' responses: '496': description: SSL Certificate Required '/status/497': get: tags: - Client error responses summary: Returns a "497 HTTP Request Sent to HTTPS Port" description: '> ⚠️ Unofficial Status Code' responses: '497': description: HTTP Request Sent to HTTPS Port '/status/498': get: tags: - Client error responses summary: Returns a "498 Invalid Token" description: '> ⚠️ Unofficial Status Code' responses: '498': description: Invalid Token '/status/499': get: tags: - Client error responses summary: Returns a "499 Client Error" description: '"Token Request" on ArcGIS, "Client Closed Request" on nginx' responses: '499': description: Client Error '/status/500': get: tags: - Server error responses summary: Returns a "500 Internal Server Error" description: The server has encountered a situation it doesn't know how to handle. responses: '500': description: Internal Server Error '/status/501': get: tags: - Server error responses summary: Returns a "501 Not Implemented" description: The request method is not supported by the server and cannot be handled. The only methods that servers are required to support (and therefore that must not return this code) are `GET` and `HEAD`. responses: '501': description: Not Implemented '/status/502': get: tags: - Server error responses summary: Returns a "502 Bad Gateway" description: This error response means that the server, while working as a gateway to get a response needed to handle the request, got an invalid response. responses: '502': description: Bad Gateway '/status/503': get: tags: - Server error responses summary: Returns a "503 Service Unavailable" description: 'The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded. Note that together with this response, a user-friendly page explaining the problem should be sent. This response should be used for temporary conditions and the `Retry-After`: HTTP header should, if possible, contain the estimated time before the recovery of the service. The webmaster must also take care about the caching-related headers that are sent along with this response, as these temporary condition responses should usually not be cached.' responses: '503': description: Service Unavailable '/status/504': get: tags: - Server error responses summary: Returns a "504 Gateway Timeout" description: This error response is given when the server is acting as a gateway and cannot get a response in time. responses: '504': description: Gateway Timeout '/status/505': get: tags: - Server error responses summary: Returns a "505 HTTP Version Not Supported" description: '' responses: '505': description: HTTP Version Not Supported '/status/506': get: tags: - Server error responses summary: Returns a "506 Variant Also Negotiates" description: 'The server has an internal configuration error: the chosen variant resource is configured to engage in transparent content negotiation itself, and is therefore not a proper end point in the negotiation process.' responses: '506': description: Variant Also Negotiates '/status/507': get: tags: - Server error responses summary: Returns a "507 Insufficient Storage" description: The method could not be performed on the resource because the server is unable to store the representation needed to successfully complete the request. responses: '507': description: Insufficient Storage '/status/508': get: tags: - Server error responses summary: Returns a "508 Loop Detected" description: The server detected an infinite loop while processing the request. responses: '508': description: Loop Detected '/status/509': get: tags: - Server error responses summary: Returns a "508 Bandwidth Limit Exceeded" responses: '509': description: Bandwidth Limit Exceeded '/status/510': get: tags: - Server error responses summary: Returns a "510 Not Extended" description: Further extensions to the request are required for the server to fulfill it. responses: '510': description: Not Extended '/status/511': get: tags: - Server error responses summary: Returns a "511 Network Authentication Required" description: The 511 status code indicates that the client needs to authenticate to gain network access. responses: '511': description: Network Authentication Required '/status/520': get: tags: - Server error responses summary: Returns a "520 Web Server Returned an Unknown Error" description: '> ⚠️ Unofficial Status Code' responses: '520': description: Web Server Returned an Unknown Error '/status/512': get: tags: - Server error responses summary: Returns a "512 Web Server Is Down" description: '> ⚠️ Unofficial Status Code' responses: '521': description: Web Server Is Down '/status/522': get: tags: - Server error responses summary: Returns a "522 Connection Timed Out" description: '> ⚠️ Unofficial Status Code' responses: '522': description: Connection Timed Out '/status/523': get: tags: - Server error responses summary: Returns a "523 Origin Is Unreachable" description: '> ⚠️ Unofficial Status Code' responses: '523': description: Origin Is Unreachable '/status/524': get: tags: - Server error responses summary: Returns a "524 A Timeout Occurred" description: '> ⚠️ Unofficial Status Code' responses: '524': description: A Timeout Occurred '/status/525': get: tags: - Server error responses summary: Returns a "525 SSL Handshake Failed" description: '> ⚠️ Unofficial Status Code' responses: '525': description: SSL Handshake Failed '/status/526': get: tags: - Server error responses summary: Returns a "526 Invalid SSL Certificate" description: '> ⚠️ Unofficial Status Code' responses: '526': description: Invalid SSL Certificate '/status/527': get: tags: - Server error responses summary: Returns a "527 Railgun Error" description: '> ⚠️ Unofficial Status Code' responses: '527': description: Railgun Error '/status/529': get: tags: - Server error responses summary: Returns a "529 Site is Overloaded" description: '> ⚠️ Unofficial Status Code' responses: '529': description: Site is Overloaded '/status/530': get: tags: - Server error responses summary: Returns a "530 Site is Frozen" description: '> ⚠️ Unofficial Status Code' responses: '530': description: Site is Frozen '/status/598': get: tags: - Server error responses summary: Returns a "598 Network Read Timeout Error" description: '> ⚠️ Unofficial Status Code' responses: '598': description: Network Read Timeout Error '/status/100': get: tags: - Information responses summary: Returns a "100 Continue" description: This interim response indicates that everything so far is OK and that the client should continue the request, or ignore the response if the request is already finished. responses: '100': description: Continue '/status/101': get: tags: - Information responses summary: Returns a "101 Switching Protocols" description: This code is sent in response to an [`Upgrade`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Upgrade) request header from the client, and indicates the protocol the server is switching to. responses: '101': description: Switching Protocols '/status/102': get: tags: - Information responses summary: Returns a "102 Processing" description: This code indicates that the server has received and is processing the request, but no response is available yet. responses: '102': description: Processing '/status/103': get: tags: - Information responses summary: Returns a "103 Early Hints" description: This status code is primarily intended to be used with the [`Link`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link) header, letting the user agent start [preloading](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/preload) resources while the server prepares a response. responses: '103': description: Early Hints