# httpstatus.codes

> Free HTTP mocking data and test endpoints for status codes, redirects, delays, headers, response streaming and compression, fixed body sizes, request inspection, and GeoIP behavior.

The documentation site is https://httpstatus.codes/. The API is available without authentication at https://mock.httpstatus.codes/ and accepts GET requests.

## Documentation

- [HTTP status codes and test endpoints](https://httpstatus.codes/): Human-readable API documentation, examples, and a raw response inspector.
- [OpenAPI description](https://httpstatus.codes/openapi.yaml): Machine-readable OpenAPI 3.1 description of the public API.
- [Postman Collection](https://httpstatus.codes/downloads/postman-collection.json): Importable request collection with grouped test scenarios and documented redirect behavior. Also supported by several other API clients.
- [HTTP request collection](https://httpstatus.codes/downloads/httpstatus-codes.http): Portable plain-text request collection for editors and clients that support the `.http` format.
- [API catalog](https://httpstatus.codes/.well-known/api-catalog): RFC 9727 Linkset for machine-readable discovery.
- [Test URL catalog (text)](https://httpstatus.codes/downloads/test-urls.txt): Copyable, grouped list of representative test URLs.
- [Test URL catalog (JSON)](https://httpstatus.codes/downloads/test-urls.json): Structured test scenarios, including required request headers where relevant.

Use the OpenAPI description as the authoritative source for routes, parameters, accepted values, limits, and response formats.

## Status code responses

- `GET /status/{code}`: Return an HTTP status response in the 1xx–5xx range. Explicitly supported codes include behavior notes where HTTP semantics cannot be reproduced completely with GET.
- Informational endpoints can send a real interim response before a final response where the server and protocol support it.
- Responses are available as `text/plain` and, where supported, JSON through content negotiation with `Accept: application/json`.

## Redirects

- `GET /redirect/{count}`: Create a chain of 1–25 server-side redirects. The default status is `307`; `301`, `302`, `303`, and `308` are also available.
- Redirect chains accept an internal `to` destination, a per-hop `delay`, and `location=relative|absolute`. The total theoretical delay of a chain may not exceed 120000 milliseconds.
- `GET /redirect-loop/a` and `GET /redirect-loop/b`: Create a continuous two-route redirect loop for testing loop detection.
- `GET /client-redirect/{type}`: Return HTML that redirects through `meta`, `js`, or `refresh`. JavaScript redirects can use `location`, `href`, `assign`, or `replace`.

## Request inspection and GeoIP

- `GET /request/ip`: Return the client IP address observed by the API.
- `GET /request/user-agent`: Return the request user agent.
- `GET /request/headers`: Return the request headers.
- `GET /request/anything` and `GET /request/anything/{path}`: Return captured request data, including an arbitrary path and query parameters.
- `GET /geo`: Resolve the client country with GeoIP data and redirect to a country-specific response. The `country` query parameter accepts an ISO 3166-1 alpha-2 override for deterministic tests.

## Response bodies and content encoding

- `GET /stream/{chunks}`: Stream 1–20 text chunks with an optional `interval` of 0–1000 milliseconds between chunks.
- `GET /bytes/{size}`: Return exactly 0–1048576 bytes as `application/octet-stream`.
- `GET /encoding/{encoding}`: Return JSON using `gzip`, `deflate`, `br`, `zstd`, or unencoded `identity` behavior.

Clients and intermediaries may buffer streamed responses or automatically decompress encoded responses. Inspect response headers or use a client that exposes transfer behavior when testing these endpoints.

## Shared request controls

- `delay` query parameter: Delay a supported response by 0–60000 milliseconds.
- `X-Delay` request header: Header alternative to the `delay` query parameter where supported.
- `X-Response` request header: Add custom response headers, except protected hop-by-hop and framing headers.
- `Accept: application/json`: Request JSON from endpoints that support content negotiation.

The service applies rate limits and may impose endpoint-specific safeguards. Do not use it for load testing. See the terms of use and OpenAPI description for current restrictions.

## Policies

- [Terms of use](https://httpstatus.codes/terms): Conditions and acceptable use for the free service.
- [Privacy policy](https://httpstatus.codes/privacy): Analytics, IP address processing, hosting, and browser storage.
- [Security contact](https://httpstatus.codes/.well-known/security.txt): How to report a vulnerability.