What are HTTP Status Codes?

HTTP status codes are standardized responses that web servers send to clients to indicate the result of a request. They are divided into five categories, each indicated by the first digit of the three-digit code.

HTTP Code Categories

Most Common Codes

When to Use Each Code in REST APIs

Important Differences

Best Practices for APIs

• Be consistent: Use the same codes for similar situations
• Use specific codes: Don't just use 200 and 500 for everything
• Include messages: The code alone may not be clear, add an explanatory message
• Document: Specify which codes your API can return for each endpoint
• Errors with details: Return JSON with error, message, and correction suggestion
• 4xx vs 5xx: Clearly differentiate client errors from server errors
• Rate limiting: Use 429 Too Many Requests when appropriate

Well-Structured Error Response Example

{
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid email",
  "details": {
    "field": "email",
    "value": "usuario@",
    "issue": "Invalid email format"
  },
  "timestamp": "2024-01-17T10:30:00Z",
  "path": "/api/users"
}

Less Known But Useful Codes

Testing HTTP Codes

# See only the status code
curl -I -s -o /dev/null -w "%{http_code}" https://exemplo.com

# See complete headers
curl -I https://exemplo.com

# Make POST and see response
curl -X POST https://api.exemplo.com/users -d '{"name":"João"}' -H "Content-Type: application/json" -v

fetch('https://api.exemplo.com/users')
  .then(response => {
    console.log('Status:', response.status);
    console.log('Status Text:', response.statusText);
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Frequently Asked Questions

Why do I receive 304 instead of 200?

304 Not Modified means the resource hasn't changed since the last request. The browser is using the cached version. This is good for performance! Want to force 200? Do a hard refresh (Ctrl+Shift+R) or disable cache in DevTools.

Can I create my own HTTP codes?

Technically yes, but DON'T DO IT. Use the standardized codes. If none fits perfectly, use the closest one and add details in the response body. Custom codes break caches, proxies, and frameworks.

What to do when I constantly see 502/503?

502 usually indicates a problem with proxy/load balancer or backend server. 503 indicates overload or maintenance. If you are the developer, check server logs. If you are a user, wait a few minutes or contact support.