RFC 9457 errors and status codes

Return application/problem+json on error responses, checked by ADP-008 and ADP-009.

Standard problem details payload

RFC 9457 obsoleted RFC 7807 with a single machine-readable error envelope.

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Your request parameters did not validate",
  "status": 422,
  "detail": "Field 'items[0].quantity' must be an integer >= 1.",
  "instance": "/v1/orders#req_01J9Z8X2M9K4"
}

HTTP status code matrix

Use consistent client and retry semantics across every endpoint.

HTTP statusMeaningTypical causeSafe to retry
400 Bad RequestMalformed syntaxInvalid JSON, missing required header, unknown query keyNo (fix payload)
401 UnauthorizedUnauthenticatedMissing or expired Bearer JWT or API credentialAfter token refresh
403 ForbiddenInsufficient permissionsValid token lacks required OAuth scope or roleNo
409 ConflictState or idempotency clashDuplicate unique key or reused Idempotency-Key with different bodyNo
412 Precondition FailedOptimistic lock mismatchIf-Match ETag is stale after concurrent updateRe-fetch and retry
422 Unprocessable ContentSemantic domain errorValid JSON syntax that violates business rulesNo
429 Too Many RequestsRate limit exceededQuota hit; pair with Retry-After and RateLimit-*Yes (after delay)