# HTTP Status API
> Every HTTP status code as an API. Look up any code (e.g. 404, 429, 503) and get its standard reason phrase, its class (1xx Informational, 2xx Success, 3xx Redirection, 4xx Client Error, 5xx Server Error), a plain-English description, the RFC that defines it, and handy flags for whether it is an error and whether it is commonly safe to retry (408, 425, 429, 500, 502, 503, 504). List every assigned code or filter by class, and enumerate the five status classes. Perfect for API clients and gateways, error pages, logging and monitoring dashboards, documentation and teaching. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 4 endpoints. Distinct from host/uptime checkers that report a live status — this is the reference dictionary of the codes themselves.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/httpstatus-api/..."
```

## Pricing
- **Free** (Free) — 680 calls/Mo, 2 req/s
- **Starter** ($1/Mo) — 5,300 calls/Mo, 8 req/s
- **Pro** ($18/Mo) — 121,000 calls/Mo, 20 req/s
- **Mega** ($54/Mo) — 625,000 calls/Mo, 50 req/s

## Endpoints

### HTTP Status

#### `GET /v1/code` — Look up a status code

**Parameters:**
- `code` (query, required, string) — Status code Example: `404`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/httpstatus-api/v1/code?code=404"
```

**Response:**
```json
{
    "data": {
        "rfc": "RFC 9110",
        "code": 404,
        "message": "Not Found",
        "category": "Client Error",
        "is_error": true,
        "description": "The server cannot find the requested resource.",
        "is_retryable": false,
        "category_class": "4xx"
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:48.437Z",
        "request_id": "33a4785a-4960-4ec3-bd72-06ffe53f702f"
    },
    "status": "ok",
    "message": "Look up a status code",
    "success": true
}
```

#### `GET /v1/list` — List status codes

**Parameters:**
- `category` (query, optional, string) — Filter 1..5 or 1xx..5xx Example: `4xx`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/httpstatus-api/v1/list?category=4xx"
```

**Response:**
```json
{
    "data": {
        "codes": [
            {
                "rfc": "RFC 9110",
                "code": 400,
                "message": "Bad Request",
                "category": "Client Error",
                "is_error": true,
                "description": "The server cannot process the request due to a client error.",
                "is_retryable": false,
                "category_class": "4xx"
            },
            {
                "rfc": "RFC 9110",
                "code": 401,
                "message": "Unauthorized",
                "category": "Client Error",
                "is_error": true,
                "description": "Authentication is required and has failed or not been provided.",
                "is_retryable": false,
                "category_class": "4xx"
            },
            {
                "rfc": "RFC 9110",
                "code": 402,
                "message": "Payment Required",
                "category": "Client Error",
                "is_error": true,
                "description": "Reserved for future use; sometimes used for paywalls/quotas.",
                "is_retryable": false,
                "category_class": "4xx"
            },
            {
                "rfc": "RFC 9110",
                "code": 403,
                "message": "Forbidden",
                "category": "Client Error",
                "is_error": true,
                "description": "The server understood the request but refuses to authorize it.",
  
…(truncated, see openapi.json for full schema)
```

### Reference

#### `GET /v1/categories` — Status classes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/httpstatus-api/v1/categories"
```

**Response:**
```json
{
    "data": {
        "categories": [
            {
                "name": "Informational",
                "class": "1xx"
            },
            {
                "name": "Success",
                "class": "2xx"
            },
            {
                "name": "Redirection",
                "class": "3xx"
            },
            {
                "name": "Client Error",
                "class": "4xx"
            },
            {
                "name": "Server Error",
                "class": "5xx"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:48.604Z",
        "request_id": "d724ae8a-5b90-470f-b683-1da61987feb7"
    },
    "status": "ok",
    "message": "Status classes",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/httpstatus-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "HTTP Status API",
        "notes": "is_retryable flags codes that are commonly safe to retry (408, 425, 429, 500, 502, 503, 504). Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/code",
                "params": {
                    "code": "e.g. 404 (required)"
                },
                "returns": "message, category, description, RFC, is_error, is_retryable"
            },
            {
                "path": "/v1/list",
                "params": {
                    "category": "optional 1..5 or 1xx..5xx"
                },
                "returns": "all codes (optionally filtered by class)"
            },
            {
                "path": "/v1/categories",
                "params": [],
                "returns": "the five status classes"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Look up HTTP status codes — the standard message, category, plain-English description, defining RFC and whether the code is an error or safely retryable. Covers all assigned 1xx–5xx codes. Pure local, no key."
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:48.693Z",
        "request_id": "bede28ec-5cdc-4837-b8da-cc57829ad7a3"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/httpstatus-api
OpenAPI spec: https://www.oanor.com/api/httpstatus-api/openapi.json