Error codes

Every error carries a machine-readable code from the closed set below. Branch on code, never on detail. The response shape and retry rules are in Errors.

Each code's type URL is https://dashboard.sproutsdata.ai/errors/<slug>, where the slug is the code with . and _ replaced by -. It redirects to that code's entry on this page.

auth.*#

Authentication and authorization.

request.*#

The request itself is the problem.

The validation payload shape:

{
  "code": "request.invalid",
  "detail": "One or more fields failed validation.",
  "extra": {
    "errors": [
      { "type": "less_than_equal", "loc": ["body", "limit"], "msg": "Input should be less than or equal to 100", "input": 500, "ctx": { "le": 100 } }
    ]
  }
}

relationship.*#

Its own namespace rather than request.invalid, because the request was valid: you named something the corpus holds more than one of. A client should branch on that differently than on a malformed body — the same reasoning that keeps auth.* separate from request.*.

feedback.*#

The feedback routes. Reporting a bad result is free, so neither of these is ever a billing question.

lists.*#

The saved lists routes. Lists are free, so none of these is a billing question.

export.*#

pagination.*#

All 422s. Recovery is always the same: throw the cursor away and re-run the search from page 1. See Pagination.

idempotency.*#

Reserved: no route sends either code today. A reused Idempotency-Key never produces an error:

• On the billed routes that honour it, the same key with the same body on the same UTC day is recognised as a retry. The same key with a different body silently starts a new request.
• On POST /v1/agents/runs, the key is required, and a reused key returns the original run's handle with 200 instead of 202, whatever the body says. It starts and charges nothing. Run keys never expire and are scoped to your workspace.

quota.*#

Infrastructure protection — always 429, never a billing question. There is no per-key request-rate limit on the REST API today; the codes below are the limits that exist. Honour Retry-After whenever it is present.

credits.*#

Commercial — a different family from quota.* by design, and the two are never conflated. A 402 is fixed by buying; a 429 is fixed by waiting. See Credits & usage.

payment.*#

Buying credits, on the dashboard's billing routes. Separate from credits.* because the failures are the buyer's to fix rather than a spend outcome:

• a 402 credits.insufficient means "you have none";
• a 402 payment.declined means "the card was refused", and sending it to a top-up screen is a dead end.

Almost all of these are reachable only with a signed-in dashboard session. The exception is payment.topup_not_found, which comes from the two top-up link routes that any credential can call. The rest are listed because code is a closed set and this page is the whole of it, as are the dashboard-only codes below.

upstream.*#

The retrieval engine or the agent engine failed. A metered call is charged only once its response is ready, so neither of these is charged. On search and lookup routes both carry Retry-After: 5.

history.*#

Other#

Dashboard only#

An API key never receives these. They come from routes that need a signed-in dashboard session, and are listed so that every code has an entry.