Guides
Errors
The error models each service uses, and HTTP status conventions
Three error shapes are in use across the estate. Check which one a given endpoint returns before you write error-handling code against it.
Umbrella API envelope
Used by Umbrella API (including the KYB endpoints under /kyb/*) and the SDK.
{ "message": "Invalid request payload" }| Field | Type |
|---|---|
message | string |
ProblemDetails (Aletheia)
{ "detail": "files[2]: file exceeds 20 MB cap" }| Field | Type | Notes |
|---|---|---|
detail | string | Always present |
trace_id | string | Present on stateless /analyze 5xx responses only |
Aletheia's 429 responses use a separate RateLimitError shape instead:
{ "error": "rate_limit_exceeded", "retry_after": <seconds> }.
ErrorResponse (KYB API spec)
From the standalone KYB API specification (services/umbrella-kyb/openapi.yaml):
{ "message": "...", "code": "INVALID_PARAMETER", "field": "country", "requestId": "..." }| Field | Type | Notes |
|---|---|---|
message | string | Required, human-readable |
code | string | Stable, machine-readable, branch on this, not on message |
field | string | For 400 validation errors, the failing request field |
requestId | string | Trace id, mirrors the x-request-id response header |
HTTP status conventions
Standard HTTP status codes are used across all services (400/401/403/404/409/422/
429/500 and related codes). See each service's guide for which codes its endpoints return.