Error Handling and Limits

Error Envelope

Common error format:

{
  "success": false,
  "error": "Validation error",
  "details": {
    "errors": [
      {
        "field": "body -> email",
        "message": "value is not a valid email address",
        "type": "value_error"
      }
    ]
  }
}

Typical Status Codes

• 400: malformed IDs, missing required context.
• 401: token/key invalid, missing, revoked, or expired.
• 403: permission denied or API key scope mismatch.
• 404: tenant/workspace/resource not found or not linked.
• 422: request validation failure.
• 429: rate limit exceeded (global or per-API-key).
• 500: unhandled/internal server error.
• 503: external dependency unavailable (for example IRN signing misconfiguration).

Rate Limits

Global IP-based limit: default 60/minute across all routes.

Per-API-key limits (for workspace API key auth):

Tier	Requests/minute
Starter	60
Professional	300
Enterprise	1,000

When rate-limited, the response is 429 Too Many Requests with a Retry-After: 60 header.

Some auth routes have stricter endpoint limits:

• POST /auth/register -> 5/minute
• POST /auth/login -> 10/minute
• POST /auth/forgot-password -> 3/minute

Retry Strategy

Safe retry candidates:

• transient 5xx
• network timeouts
• dispatch retry flows where endpoint explicitly supports retry

Avoid blind retry on:

• 4xx validation errors
• 403 scope/permission failures
• business rule failures without payload correction

Logging Recommendations

Capture these fields in client logs:

• request path and method
• tenant/workspace IDs
• operation ID or local correlation ID
• HTTP status and normalized error code/message