H

API Documentation

The HTTP Echo API allows you to test any HTTP status code with optional customization through query parameters. All endpoints are free, CORS-enabled, and require no authentication.

Base URL

https://codes.uncodigo.com

Endpoints

GET /http/{code}

Returns the requested HTTP status code with JSON metadata

POST /http/{code}

Same as GET, accepts POST requests

PUT /http/{code}

Same as GET, accepts PUT requests

DELETE /http/{code}

Same as GET, accepts DELETE requests

PATCH /http/{code}

Same as GET, accepts PATCH requests

HEAD /http/{code}

Returns headers only, no body

OPTIONS /http/{code}

Returns CORS headers and allowed methods

Query Parameters

Parameter Type Description Example
delay number (ms) Delay the response by N milliseconds (max 30000) /http/200?delay=2000
body string Custom response body /http/200?body=Hello+World
content_type string Custom Content-Type header /http/200?content_type=text/plain
headers JSON Additional response headers as JSON object /http/200?headers={"X-Custom":"value"}
redirect_to string (URL) Destination URL for 3xx redirects /http/301?redirect_to=https://example.com
retry_after number (seconds) Value for Retry-After header (429, 503) /http/429?retry_after=60
allow string Allowed methods for 405 response /http/405?allow=GET,POST

Quick Start

The simplest way to test the API is with curl: 

curl https://codes.uncodigo.com/http/200

Code Examples

curl 
# Get a 200 OK response
curl -i https://codes.uncodigo.com/http/200

# Simulate a slow server
curl -i "https://codes.uncodigo.com/http/200?delay=5000"

# Test rate limiting with retry info
curl -i "https://codes.uncodigo.com/http/429?retry_after=60"

# Custom redirect
curl -i "https://codes.uncodigo.com/http/301?redirect_to=https://example.com"

# Custom response body
curl -i "https://codes.uncodigo.com/http/200?content_type=text/plain&body=Custom+response"
JavaScript (fetch) 
// Test a 404 response
const response = await fetch('https://codes.uncodigo.com/http/404');
console.log(response.status); // 404
const data = await response.json();
console.log(data);

// With delay
const slowResponse = await fetch('https://codes.uncodigo.com/http/200?delay=2000');

// Custom headers
const customResponse = await fetch('https://codes.uncodigo.com/http/200?headers={"X-Custom":"value"}');
console.log(customResponse.headers.get('X-Custom')); // value
Python (requests) 
import requests

# Test a 500 error
response = requests.get('https://codes.uncodigo.com/http/500')
print(response.status_code)  # 500
print(response.json())

# With query parameters
response = requests.get('https://codes.uncodigo.com/http/200', params={
    'delay': 1000,
    'content_type': 'text/plain'
})
Go 
package main

import (
    "fmt"
    "net/http"
    "io"
)

func main() {
    resp, err := http.Get("https://codes.uncodigo.com/http/418")
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    body, _ := io.ReadAll(resp.Body)
    fmt.Printf("Status: %d\n", resp.StatusCode)
    fmt.Printf("Body: %s\n", body)
}

Response Format

By default, the API returns JSON with the following structure: 

{
  "code": 404,
  "name": "Not Found",
  "description": "The requested resource could not be found...",
  "spec": "RFC 9110, Section 15.5.5",
  "request": {
    "method": "GET",
    "url": "https://codes.uncodigo.com/http/404",
    "headers": { ... }
  }
}

CORS

All API endpoints include permissive CORS headers, allowing you to use them from any origin, including browsers: 

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
Access-Control-Allow-Headers: *

Rate Limiting

The API includes rate limit headers in all responses:

  • X-RateLimit-Limit - Maximum requests allowed
  • X-RateLimit-Remaining - Requests remaining in current window
  • X-RateLimit-Reset - Unix timestamp when the limit resets

For production use with higher limits, consider deploying your own instance.

Error Handling

If you request an invalid status code, the API returns a 400 Bad Request: 

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid HTTP status code",
  "message": "Code 999 is not a recognized HTTP status code",
  "valid_range": "100-599 (plus common non-standard codes)",
  "docs": "https://codes.uncodigo.com/codes"
}

Use Cases

Error Handling Testing

Test how your application handles different HTTP error conditions without needing to trigger real failures.

Mock Servers

Use in development when APIs aren't ready. Simulate success and error responses to build resilient clients.

CI/CD Testing

Include in automated test suites to verify your HTTP client logic handles various status codes correctly.

Learning & Teaching

Perfect for learning about HTTP status codes and demonstrating how different codes behave in practice.