Errors
Every error, on the REST API and the MCP server alike, uses one JSON envelope
with a stable, machine-readable code:
{ "error": { "code": "invalid_request", "message": "Malformed JSON body" } }Branch on code, not on the human-readable message (which may change —
though validation messages include a corrected example call where one helps).
Every response also carries an X-Request-ID header. Quote it when asking
"what happened with this search?" — we keep a per-request record of how the
query was interpreted, what was relaxed, what was excluded and why retrieval
stopped, so support can answer from the log rather than guesswork.
Seeing 5xx responses or timeouts across the board rather than on one query?
Check status.disburse.dev before digging
into your own code — it reports the API, MCP, dashboard and website
independently of our infrastructure, so it answers even during an outage.
Codes
| Code | HTTP | Meaning |
|---|---|---|
invalid_request | 400 | Malformed body or invalid parameters |
unauthorized | 401 | Missing, unknown, disabled, or exhausted key |
unparseable_query | 422 | The natural-language query couldn't be understood |
insufficient_credits | 402 | Your organization is out of credits |
rate_limited | 429 | Too many requests, see Rate limits |
no_data | 404 | The request was valid but matched nothing |
not_found | 404 | Unknown route |
method_not_allowed | 405 | Wrong HTTP method for the route |
timeout | 504 | An upstream lookup exceeded its deadline |
unavailable | 503 | A dependency was temporarily unreachable |
internal | 500 | Unexpected server error |
Retrying
rate_limitedandtimeoutare transient; retry after a short backoff.rate_limitedresponses include aRetry-Afterheader.unavailableis also transient; back off and retry.invalid_request,unauthorized, andunparseable_queryare your side, fix the request rather than retrying it.insufficient_creditsclears the moment credits do: top up or upgrade on the dashboard's billing page, then retry. Verification endpoints are never gated.no_dataisn't a failure: the query was fine, there just wasn't a match.