# 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.