Errors and rate limits

Error envelope

All failure responses use the canonical JSON envelope (ADR-021, SPEC-031):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable summary",
    "details": {}
  },
  "request_id": "<uuid>"
}

Common codes for integrators: AUTH_REQUIRED, FORBIDDEN, VALIDATION_ERROR, INTAKE_*, IDEMPOTENCY_KEY_MISMATCH (409), IDEMPOTENCY_IN_PROGRESS (409), IDEMPOTENCY_KEY_INVALID (422), webhook URL validation (422), WEBHOOK_SUBSCRIPTION_LIMIT_EXCEEDED (409), rate-limit 429.

Rate limits

Inbound limits follow ADR-030 and P5-048:

• Intake submit paths are rate-limited per tenant/user key schema documented in ADR-030
• Expect X-RateLimit-* headers where configured and Retry-After on 429

Do not busy-loop on 429 — honor Retry-After.