IDCanopy Developers
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 and the SDK. The KYB endpoints under /kyb/* use their own envelope, below.

{ "message": "Invalid request payload" }
FieldType
messagestring

ProblemDetails (Aletheia)

{ "detail": "files[2]: file exceeds 20 MB cap" }
FieldTypeNotes
detailstringAlways present
trace_idstringPresent 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" }
FieldTypeNotes
statusbooleanAlways false on an error. Absent on one case: a 401 for a missing bearer token is { "error": "..." } alone
errorstringOn 400 from the service, 401, 500, 502 and 503
messagestringOn 400 from the gateway's own validation (prefixed Validation failed:), 403 and the account transaction limit 429
codestringOpen set. Known: DAILY_LIMIT_REACHED, RATE_LIMITED, COMPANY_NOT_IN_TRANSACTION
providerstringWith DAILY_LIMIT_REACHED, and on a 429 passed through from a provider
limit, remainingintegerOn 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.

On this page