Get started
Errors
The gateway returns a small JSON envelope for errors it generates. Upstream errors are forwarded as-is.
Gateway envelope
Errors produced by the gateway always look like this:
json
{
"status": "error",
"message": "Invalid authentication token"
}Status codes
| Status | When | Typical message |
|---|---|---|
400 | Invalid or missing fields (usually upstream) | Validation details from the service |
401 | Missing or invalid Bearer token (or share password) | Invalid authentication token |
403 | Authenticated, but not allowed | Role gate, quota, license, or identity block |
404 | Unknown path or hidden cross-tenant id | Laravel not-found JSON, or generic not-found |
409 | Conflict (already terminal, already sealed, …) | Stable error_code from the service |
429 | Rate limit or notification quota | SMS_QUOTA_REACHED / WHATSAPP_QUOTA_REACHED |
502 | Upstream is unreachable | Upstream API is unreachable |
503 | Service disabled, URL missing, or retryable outage | Upstream API is disabled / TIMESTAMP_UNAVAILABLE_RETRY |
Upstream errors
Successful responses and most 4xx validation errors come straight from the target service: same status, same body, including binary downloads. The gateway does not rewrite those payloads.
| Area | Body |
|---|---|
| Auth / notifications | { "status": "error", "message": "..." } or errors on validation. Domain failures add error_code. |
| Signing | { "error": "...", "error_code": "..." } |
| Workflows | Laravel validation errors, plus codes such as STEP_NOT_CANDIDATE, WORKFLOW_STRUCTURE_LOCKED, MODEL_LIMIT_REACHED |
| Vault / AI | { "error": { "code": "forbidden", "message": "..." } } |
| Verification | { "error": { "code": "INVALID_DOCUMENT", "message": "...", "details": {} } } |
Read status + message when present, otherwise error.code or error_code. Ignore unknown properties.
Common error codes
| Code | Meaning |
|---|---|
LICENSE_EXPIRED / LICENSE_READONLY | Company license blocks access or writes |
SEAT_LIMIT_REACHED | Reactivating a user would exceed the license seat cap |
MFA_CHALLENGE_INVALID / MFA_CODE_INVALID | Login MFA challenge expired or code is wrong |
IDENTITY_* | Public identity or envelope identity (see Signing) |
SIGNATURE_QUOTA_REACHED / SMS_QUOTA_REACHED | Company volume exhausted |
ENVELOPE_ALREADY_TERMINAL / ENVELOPE_NOT_TERMINAL | Cancel / delete / access on the wrong envelope state |
document_sealed / already_sealed | Vault immutability |
SEAL_CONSENT_REQUIRED | Public sign applied a company seal without consent |