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 status | Meaning | Typical cause | Safe to retry |
|---|---|---|---|
400 Bad Request | Malformed syntax | Invalid JSON, missing required header, unknown query key | No (fix payload) |
401 Unauthorized | Unauthenticated | Missing or expired Bearer JWT or API credential | After token refresh |
403 Forbidden | Insufficient permissions | Valid token lacks required OAuth scope or role | No |
409 Conflict | State or idempotency clash | Duplicate unique key or reused Idempotency-Key with different body | No |
412 Precondition Failed | Optimistic lock mismatch | If-Match ETag is stale after concurrent update | Re-fetch and retry |
422 Unprocessable Content | Semantic domain error | Valid JSON syntax that violates business rules | No |
429 Too Many Requests | Rate limit exceeded | Quota hit; pair with Retry-After and RateLimit-* | Yes (after delay) |