Skip to content
/
Errors & Tracing
Last updated

Errors & Tracing

Standard error body

All errors return a body with:

  • traceId
  • error.code
  • error.message
  • optional error.details

x-kaito-trace-id

All responses include x-kaito-trace-id. When opening a support ticket, include the trace id.

traceId in error body matches this header value.

Common error codes

  • INVALID_REQUEST
  • UNAUTHORIZED
  • FORBIDDEN
  • NOT_FOUND
  • QUOTE_EXPIRED
  • CORRIDOR_NOT_SUPPORTED
  • PROVIDER_UNAVAILABLE
  • RATE_LIMITED
  • IDEMPOTENCY_CONFLICT
  • BRIDGE_ENDORSEMENT_REQUIRED

Bridge account compliance remediation

When creating a bank account for a Bridge-backed country/account type, Bridge may require the end user to complete KYC or endorsement remediation before the account can be created. In that case POST /v1/accounts returns HTTP 409 with:

  • error.code: BRIDGE_ENDORSEMENT_REQUIRED
  • error.details.endorsement: the missing Bridge endorsement, for example pix
  • error.details.complianceUrl: the Bridge-hosted remediation URL, when Bridge provides one

The failed account is not persisted, so GET /v1/accounts does not return the remediation URL later. Retry POST /v1/accounts to obtain the current Bridge remediation response if the link is needed again.

Webhooks