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, andRetry-Afteron429.
Do not busy-loop on 429 — honor Retry-After.