Errors: problem types and how to handle them

Every Bridge to Brands error is RFC 9457 problem+json with a stable type URL. The catalogue of problem types and what to do about each one.

Errors are application/problem+json (RFC 9457). type is a stable URL under https://brdg2b.ai/problems/. Portal-side failures carry brand and, for portal_down, retry_after. Include the X-Request-Id in support requests.

{
  "type": "https://brdg2b.ai/problems/brand_not_connected",
  "title": "Brand not connected",
  "detail": "This account has not connected hoka. Ask the account owner to connect it in app.brdg2b.ai/brands.",
  "brand": "hoka"
}

Type	Meaning	What to do
`validation_error`	the request failed validation; unknown fields are rejected	fix the request
`brand_not_connected`	the account has not connected the brand	the account owner connects it in the web app
`brand_not_supported`	no connector for that brand code	check `GET /v1/brands`
`capability_unavailable`	the brand does not support the operation	check the brand’s `capabilities`
`credentials_invalid`	the portal rejected the stored login	the account owner re-enters the portal password
`portal_down`	the portal is unavailable	retry after `retry_after`
`portal_rejected`	the portal refused the request	read `detail`; fix the line or ship-to
`portal_changed`	the portal response no longer matched the connector	retry later
`push_busy`	another order is staging on the same connection	retry shortly
`draft_left_behind`	the vendor may hold a draft carrying this order	check the portal, then `POST /orders/{id}/acknowledge-draft`
`rate_limited`	a key or account limit was hit	honour `Retry-After`

Over MCP, the same problems come back as tool results, not exceptions, so the model can recover.

Errors: problem types and how to handle them

Related