---
title: "Errors: problem types and how to handle them"
description: "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."
canonical: https://brdg2b.ai/docs/errors
updated: 2026-10-16
---

# Errors: problem types and how to handle them

Bridge to Brands is a product of RunOps Inc.

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.

```json
{
  "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.