Skip to main content
The Kash REST API returns errors as RFC 7807 Problem Details, with 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 carry type: "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

The code field is part of the public API contract:
  • Adding a new code is non-breaking. Your client should fall through to a generic handler for any code it doesn’t recognise.
  • Renaming a code is 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 code is breaking.
The 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).
By default the SDK retries 429 and 5xx responses (up to 3 retries, with exponential backoff that honours 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).

All error codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

410 Gone

422 Unprocessable Content

429 Too Many Requests

500 Internal Server Error

503 Service Unavailable

504 Gateway Timeout