Errors
Every refusal Probably's API answers with: its outcome, HTTP status and what to do about it.
A refusal is an answer you can act on, not an exception. Over HTTP it answers with the status its outcome means and a JSON body; over MCP it is the tool's result with isError and the same body as structured content.
{
"outcome": "rate-limited",
"message": "Too many attempts. Try again shortly.",
"retryAfterSeconds": 30
}| Field | What it says |
|---|---|
outcome | What stopped it, from the catalog below. Branch on it, never on the message. |
message | What happened, in words a person can read. It never carries an internal error's text. |
retryAfterSeconds | Only with rate-limited: how long to wait, as the Retry-After header also says. |
A missing, malformed or revoked API key is refused the same way, with the outcome unauthorized and status 401.
Refusals at the boundary
A request refused before it reaches its tool or the key check, such as one sent from a browser, one over the size limit, or one that failed unexpectedly at the boundary, answers with the status from the same table but another body: the outcome is in code, not outcome.
| Field | What it says |
|---|---|
code | What stopped it, from the same catalog. |
error | What happened, in words a person can read. |
requestId | The request's ID, also in the x-request-id header. Quote it to us. |
Outcomes
This table is generated from the outcome-to-status map the API itself answers with, and the API key check's refusal.
| Outcome | Status | What to do |
|---|---|---|
invalid | 400 | The input doesn't match the tool's schema, names something it can't use, or reuses a request key with other input or for another tool. The message names the fields; fix them and send again. |
unauthorized | 401 | The API key is missing, malformed or revoked. Send a current key as Authorization: Bearer prb_.... |
not-enough-credits | 402 | The organization's credits don't cover the work. An admin adds credits in the studio; the confirmation stays pending until it expires, so confirm it again once there is room. |
spend-cap-reached | 402 | A spend cap on the organization or the Space would be passed. An admin raises it in the studio; the confirmation stays pending until it expires. |
access-changed | 403 | The member's access changed during the call (removed, or their role changed). Read again; if it persists, the key no longer reaches this. |
cross-site | 403 | The request carried an Origin header. API keys are for servers; call the API from your backend, never from a page. |
reauth | 403 | The person must sign in again in the studio before this can be done. |
denied | 404 | The key's member may not do this to what the request names. It shares not-found's status, 404, so a client that reads only statuses learns nothing more; the body names denied. |
not-found | 404 | Nothing by that ID is reachable with this key: it doesn't exist, it's in another organization or outside the key's Space, or the key isn't offered the tool. Check the ID and the key's scope. |
change-outdated | 409 | The change, or the draft it was prepared from, moved on since it was prepared. Read the video again and prepare the change afresh. |
conflict | 409 | The request conflicts with the current state, such as a change on something archived. Read the current state, then decide. |
price-changed | 409 | Nothing started: the work is charged at a fixed price, and the price it was shown at isn't the price now (or none was, as for a confirmation prepared before prices were fixed). Prepare it again and show the person the new price. |
confirmation-expired | 410 | The confirmation is older than its expiry. Call the prepare_* tool again for a fresh preview and confirmation. |
gone | 410 | What the request names has expired or been used. Start again from a fresh read. |
too-large | 413 | The body is over 64 KB. Send less in one call. |
refused | 422 | The request is understood but can't be done as asked; the message says why. Change the request, don't retry it unchanged. |
rate-limited | 429 | Too many calls. Wait retryAfterSeconds (also the Retry-After header) before calling again. |
failed | 500 | Something went wrong on our side. The message carries a reference; retry with the same request key, and quote the reference if it persists. |
unavailable | 503 | A service Probably depends on is unavailable. Retry later with backoff. |
When something went wrong on our side
A failed answer's message carries a reference. Retry with the same request key after a backoff; if it keeps failing, send us the reference and the time, never your key.