Error Handling

The error envelope follows RFC 9457 problem+json. Codes are stable ? see Standards ? Error codes.

RFC 9457 problem+json

{
  "error": {
    "type": "https://errors.ghasi.io/validation/field_required",
    "code": "validation.field_required",
    "title": "Missing required field",
    "status": 422,
    "detail": "Field 'email' is required.",
    "instance": "/api/v1/users",
    "errors": [
      {
        "field": "email",
        "code": "required"
      }
    ],
    "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
    "requestId": "req_01J9Z9F3KX5N2RQ4P7M8YQK6T2",
    "retriable": false,
    "retryAfter": null,
    "docUrl": "https://docs.ghasi.io/errors/validation/field_required"
  }
}

Common codes

Code	HTTP	When
validation.field_required	422	Required field missing
validation.field_invalid	422	Field type/format invalid
auth.invalid_token	401	JWT missing, malformed, expired, or bad signature
authz.forbidden	403	Authenticated but not permitted
authz.tenant_not_a_member	403	X-Tenant-Id mismatches JWT tid
idempotency.replay_mismatch	409	Same Idempotency-Key, different request body
concurrency.version_conflict	412	If-Match version mismatch
rate_limit.exceeded	429	Tenant or principal rate limit hit