Skip to main content

Integration guide

Errors and rate limits

Error envelope, rate-limit headers, and retry guidance for integrators.

Field-level detail for every endpoint is in the API reference.

Error envelope

Every failure response uses one JSON error format: an error object with code, message, request_id, and optional details. Include the request_id when you contact support.

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

Branch on error.code, not on error.message (messages may change wording).

Common codes for integrators: AUTH_REQUIRED (401), INSUFFICIENT_ROLE (403), VALIDATION_ERROR (422), INTAKE_*, FILE_TYPE_NOT_ALLOWED (422), FILE_TOO_LARGE (422), IDEMPOTENCY_KEY_MISMATCH (409), IDEMPOTENCY_IN_PROGRESS (409), IDEMPOTENCY_KEY_INVALID (422), webhook URL validation (422), WEBHOOK_SUBSCRIPTION_LIMIT_EXCEEDED (409), RATE_LIMIT_EXCEEDED (429).

Rate limits

  • Intake submit paths are rate-limited per tenant and per user.
  • Responses carry X-RateLimit-* headers where limits are configured, and Retry-After on 429.

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