apiguide.dev

Authoritative design patterns for developer-friendly APIs. Standardize your error schemas, document your status codes, secure your headers, and master the HTTP specification.

Index counts:21 Errors•63 Status Codes•46 Headers•18 Methods•41 Guides•21 Specs•34 Tools

Reference Directories

API Errors →

Standard Problem+JSON structures for validation, authentication, and state conflicts.

21 schemas defined

Status Codes →

Semantics and API usage boundaries for informational, redirection, client, and server codes.

63 codes cataloged

HTTP Headers →

Full specification metadata covering standard authorization, concurrency, and rate limits.

46 headers cataloged

Request Methods →

Guarantees of safety, idempotence, and cacheability for HTTP request verbs.

18 request verbs

Developer Guides →

Architectural guides detailing HTTP Caching, CORS preflight flow, and token security.

41 guides available

API Specifications →

In-depth references covering schema standard specifications like OpenAPI, AsyncAPI, and JSON Schema.

21 standards cataloged

API Tooling →

Curated directory of industry tools covering documentation, mock testing, gateways, and observability.

34 tools review cataloged

Problem+JSON Guide →

Understand the RFC 9457 specification and why using URIs for error types is crucial.

RFC 9457 / RFC 7807

Common API Scenarios

How to handle rate limits?

Protect your servers from abuse by implementing uniform rate-limiting responses. Learn which headers to write and when to drop client requests.

HTTP 429 Status Retry-After Header RateLimit Error Schema

How to lock concurrency?

Prevent "mid-air collisions" and race conditions where multiple clients update the same database entity concurrently using optimistic locking.

ETag Header If-Match Header HTTP 412 Precondition Failed

How to structure validation failures?

Return clear, nested parameter-level validation errors to clients when form submissions fail, using RFC 9457 standard patterns.

HTTP 422 Status Validation Error Schema Problem+JSON Standard

How to guarantee request idempotence?

Ensure safe retries for state-mutating requests (like payment actions) without duplicate charge processing by utilizing unique header keys.

Idempotency-Key Header POST Request Verb API Security Guide

The Standardized Error Pattern

Web APIs should use RFC 9457 (Problem+JSON) error responses rather than arbitrary ad-hoc properties, providing predictable error categorization.

🚫 Bad Ad-hoc Error Payload

{
  "error": true,
  "msg": "Invalid email format",
  "code": 9942,
  "timestamp": 178598402
}

✅ Standard RFC 9457 Problem+JSON

{
  "type": "https://apiguide.dev/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The request body validation parameters failed.",
  "instance": "/users/102/profile",
  "invalid_params": [
    {
      "name": "email",
      "reason": "Email address must contain '@' sign"
    }
  ]
}