Providing a detailed list of error codes that API consumers can expect when integrating with an API, sharing common HTTP status codes, but also custom errors returned. Having a single page helps communicate errors with consumers, but it also helps producers evaluate how errors are handled across many different APIs.

Also known as: Errors, Problem Details, Status Codes

Example

- type: ErrorCodes
  url: https://developers.example.com/errors

Standards

• IETF RFC 9457 — Problem Details for HTTP APIs
• IETF (historic) RFC 7807 — Problem Details for HTTP APIs (obsoleted by RFC 9457)
• IETF RFC 9110 — HTTP Semantics (Status Codes §15)
• IETF RFC 6585 — Additional HTTP Status Codes
• IETF RFC 8288 — Web Linking
• gRPC project gRPC Status Codes
• Vendor guideline google.rpc.Status / google.rpc.ErrorInfo
• OpenAPI Initiative OpenAPI Specification (Responses Object)
• Community spec JSON:API Errors

HTTP Headers

Status Codes

• 400 Bad Request — RFC 9110 §15.5.1
• 401 Unauthorized — RFC 9110 §15.5.2
• 403 Forbidden — RFC 9110 §15.5.4
• 404 Not Found — RFC 9110 §15.5.5
• 409 Conflict — RFC 9110 §15.5.10
• 422 Unprocessable Content — RFC 9110 §15.5.21
• 429 Too Many Requests — RFC 6585 §4
• 500 Internal Server Error — RFC 9110 §15.6.1
• 503 Service Unavailable — RFC 9110 §15.6.4

Media Types

• application/problem+json — RFC 9457 — Default Problem Details payload. Fields include type, title, status, detail, instance.
• application/problem+xml — RFC 9457
• application/vnd.api+json — JSON:API — Carries an errors array with id, status, code, title, detail, and source pointers.

OpenAPI Expression

• responses (OpenAPI 3.x) — Per-operation map of HTTP status codes to Response objects describing error shapes.
• components.responses (OpenAPI 3.x) — Reusable error responses (e.g. NotFound, RateLimited) referenced across operations.
• components.schemas.Problem (OpenAPI 3.x) — Conventional schema name for the RFC 9457 Problem Details object.

Link Relations

• help — RFC 8288 / IANA — Often used inside Problem Details "type" or via Link header to point at error documentation.
• about — RFC 6903

Governance Rules

• oas-operation-4xx-response (Spectral built-in) — Operations should declare at least one 4xx response.
• oas-default-response (Spectral built-in) — A default response covers unspecified error cases.
• naftiko-error-codes (Naftiko Sandbox (error-codes/*.yml)) — Checks for problem+json usage and consistent error schemas.

Risk & Compliance

OWASP:

• OWASP API Security Top 10: API8:2023 Security Misconfiguration

Compliance:

• PCI DSS v4 Req. 6.2 — secure error handling without leaking sensitive data
• SOC 2 CC7.2 — system monitoring of errors and anomalies

Security: Verbose error responses can leak stack traces, internal hostnames, query fragments, or PII. Use Problem Details with stable type URIs, redact sensitive fields, and ensure error bodies do not vary based on existence of resources in ways that enable enumeration.

Tools

• Spectral — Linter (Apache-2.0)
• zalando/problem (Java) — Library (MIT)
• problem-details (Python) — Library
• ProblemDetails (.NET) — Framework
• oasdiff — Breaking-change detector (Apache-2.0)

Suggested Metrics

• 4xx_rate — Share of responses with client-error status codes.
• 5xx_rate — Share of responses with server-error status codes; SLO-critical.
• problem_json_coverage — Fraction of error responses using application/problem+json.
• top_error_types — Most frequent Problem type URIs; informs documentation and DX work.

Example Implementations

• GitHub — Documented error responses with message and documentation_url fields.
• Stripe — Typed error categories (api_error, card_error, idempotency_error) with codes and decline reasons.
• Google — google.rpc.Status with typed details (ErrorInfo, BadRequest, QuotaFailure).
• Microsoft Graph — OData-style error envelope with code, message, innerError, and target fields.

Related Properties

• Authentication
• Rate limits
• Status page
• Versioning
• Lifecycle

Tags

• Errors
• Status

All Common Properties