Content-Type: application/problem+json. Every response carries a stable
code and a type URL that resolves to that code’s page in this catalogue:
Some codes add extension members at the top level of the body, next to
the standard fields: for example
inFlight and maxInFlight on
TRADE_IN_FLIGHT_LIMIT_EXCEEDED,
queueAgeSeconds on
TRADE_ADMISSION_BUSY, and
requested, supported and current on
API_VERSION_UNSUPPORTED.
Each code’s page documents its members.
Retryable errors (429, 503 and 504) carry a Retry-After header in
seconds. Rate-limited responses also carry X-RateLimit-Limit,
X-RateLimit-Remaining and X-RateLimit-Reset; see
Rate limits. For how errors fit
the rest of the API, see Errors.
Responses outside the catalogue
A few responses come from the API’s framework layer rather than an endpoint. They use the same problem shape but carrytype: "about:blank":
an unknown path returns 404 with code: "ROUTE_NOT_FOUND", a request the
framework rejects before it reaches an endpoint can return 400 with
code: "BAD_REQUEST", and a request that runs out of time returns
REQUEST_TIMEOUT. Your
client should fall back to the HTTP status for any code it does not
recognise.
Stability promise
Thecode field is part of the public API contract:
- Adding a new
codeis non-breaking. Your client should fall through to a generic handler for any code it doesn’t recognise. - Renaming a
codeis breaking and requires a new API version. - Repurposing a
code(changing what causes it) is breaking and requires a new API version. - Changing the HTTP status of an existing
codeis breaking.
title is also stable; it appears in customer logs and dashboards.
The detail string is not stable and may be reworded in any release.
instance and requestId are the fastest route to support: quote them
when you report a problem.
Branching on errors
The TypeScript SDK (@kashdao/sdk) turns every problem response into a
typed error class, chosen from the HTTP status (and, for a few codes, the
code). Every class extends KashError, which exposes code,
statusCode, requestId, isRetryable and extensions (the extension
members above).
Retry-After) and sends an
Idempotency-Key on every POST so retries cannot execute twice. Use
KashError.isKashError(err) instead of instanceof if errors may cross
a realm boundary (for example between a worker and the main thread).