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 and the SDK. The KYB endpoints under /kyb/* use their own envelope, below.
{ "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> }.
KYB envelope (/kyb/*)
From the KYB 3.0.0 specification (ErrorResponse in the KYB group of the
Umbrella API reference). The exact shape depends on which
layer produced the error; not every field is present on every error. Branch on the HTTP status and on
code when present, never on the text of error or message.
{ "status": false, "error": "company_id does not belong to transaction_id", "code": "COMPANY_NOT_IN_TRANSACTION" }| Field | Type | Notes |
|---|---|---|
status | boolean | Always false on an error. Absent on one case: a 401 for a missing bearer token is { "error": "..." } alone |
error | string | On 400 from the service, 401, 500, 502 and 503 |
message | string | On 400 from the gateway's own validation (prefixed Validation failed:), 403 and the account transaction limit 429 |
code | string | Open set. Known: DAILY_LIMIT_REACHED, RATE_LIMITED, COMPANY_NOT_IN_TRANSACTION |
provider | string | With DAILY_LIMIT_REACHED, and on a 429 passed through from a provider |
limit, remaining | integer | On the account transaction limit 429 only |
Which codes: 400 is validation, by the gateway or passed through from the KYB service with its message;
401 and 403 are authentication and product access; 404 and 409 are reserved pass-through codes the
service does not currently send; 429 is a provider's daily spend limit, the suggest rate limit (with
Retry-After) or the account transaction limit; 500 is an unexpected error in the gateway route, such as
a body that is not valid JSON; 502 means the KYB service refused the gateway (a configuration problem on
our side, not your request); 503 means the KYB service answered with a server error or did not answer.
The KYB guide lists what triggers each.
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.