Troubleshooting - Ripio B2B API

Error contract

Every error response from the widget’s API carries a code and a detail:

{
  "code": 40001,
  "detail": "Authentication credentials were not provided."
}

detail is a plain string, with one exception: when the request itself failed validation, detail is an object keyed by the field that failed instead — one array of messages per field, the same shape you’d get from any field-level validation error.

{
  "code": 20000,
  "detail": {
    "requested_operations": {
      "0": ["\"no-existe\" is not a valid choice."]
    }
  }
}

20000 is the only code that carries this shape today — every other code below always answers with a single string message.

Code	Meaning
`20000`	Validation error — something in the request is malformed. `detail` is an object keyed by field, not a string.
`20002`	Not found.
`40000`	Authentication failed — invalid credentials on `POST /auth`.
`40001`	Not authenticated — no session token was provided.
`40002`	Permission denied — the session doesn’t have this operation enabled.
`40003`	Session not found or expired.
`40004`	Throttled — too many requests.
`50000` and above	An internal or upstream error. Retry the request.

Session expired vs. session not found

A user’s session can fail in two different ways, and the widget’s screen tells them apart:

Situation	What it means	What to do
Token invalid or expired	The JWT itself failed validation.	Mint a new token via `POST /auth` and re-embed the widget.
Session not found	The token is valid, but the session behind it is gone.	Same fix — mint a new token — but the user had already started interacting, so this can surface mid-flow rather than only on load.