Errors
Errors from /v1 use one JSON envelope with a stable machine-readable code and a human-readable message. This page lists every code, its HTTP status, what causes it and how to fix it.
What does an error look like?#
Error responses
{
"error": {
"code": "limit_too_large",
"message": "limit can be at most 50 on your plan"
}
}{
"error": {
"code": "invalid_request",
"message": "request did not validate",
"details": [
{
"loc": ["body", "items", "0", "radius_km"],
"msg": "Input should be less than or equal to 500",
"type": "less_than_equal"
}
]
}
}{
"error": { "code": "rate_limited", "message": "too many requests; slow down" }
}- Branch on
error.code, not onmessage. Messages are for people and may be reworded. detailsappears only oninvalid_requestfrom validation.- Rate-limit and quota headers are sent on errors too. See Rate limits.
Error codes#
| Code | HTTP | Meaning | Fix |
|---|---|---|---|
invalid_request | 422 | The body or a query parameter failed validation: wrong type, out of range, too long, not JSON, or an exposure check with no items. details lists up to 20 problems with loc, msg and type. | Fix the fields named in details[].loc. Check limits such as limit (1 to 500) and radius_km (at most 500). |
limit_too_large | 400 | limit is above your plan's page size: 50 on Sandbox, 200 on Starter, 500 on Pro and Enterprise. | Lower limit and page with offset, or narrow the query with filters. |
invalid_limit | 400 | limit is below 1. Out-of-range values are usually caught earlier as invalid_request. | Send a limit of at least 1. |
invalid_failure_layer | 400 | failure_layer on GET /v1/forecast is not a known layer. | Use an id from GET /v1/failure-layers. |
invalid_items | 400 | A watchlist item has no id, has an unknown kind, or the call would go over your plan's watched-item limit. The message says which. | Give every watchlist item an id, or remove items or upgrade to raise the limit. |
invalid_webhook | 400 | The webhook URL or filters were refused: not https, a port other than 443 or 8443, a private address, a host that does not resolve, credentials in the URL, a bad min_severity or unknown events, a list over 500 entries, or no webhooks left on your plan. | Fix the URL or filters as the message says. Sandbox has no webhooks; Starter allows 3, Pro 20. |
missing_api_key | 401 | No Authorization: Bearer or X-API-Key header. | Send your key. See Authentication. |
invalid_api_key | 401 | The key is unknown or revoked, or the organisation is disabled. | Check for typos and whitespace; create a new key in the console if it was revoked. |
plan_required | 403 | The plan does not include exposure checks. Every current plan does, so you should not see this. | Contact us if you do. |
not_found | 404 | No signal, watchlist, item, event, airport, carrier or active webhook with this id. Signal ids from another account and internal ids without your suffix are also not found. Carriers with no data yet return it too. | Use ids returned to your own key. Airport codes are IATA. |
payload_too_large | 413 | The request body is over 2 MB. | Split large exposure checks or item uploads into several calls. |
rate_limited | 429 | Your organisation went over its requests per minute. Retry-After says how many seconds to wait. | Wait for Retry-After, then retry with backoff. See Rate limits. |
quota_exceeded | 429 | The monthly request quota is used up. It resets at 00:00 UTC on the first of the month. | Upgrade the plan or wait for the next month. Retrying sooner does not help. |
daily_data_limit | 429 | The organisation has received its plan's daily number of records from list endpoints (500 on Sandbox, 50,000 on Starter, 500,000 on Pro). It resets at 00:00 UTC. | Poll with since and filters instead of re-reading everything; contact us for bulk access. |
internal_error | 500 | Something failed on our side. | Retry with backoff. If it persists, contact us with the time and endpoint. |
Which errors should I retry?#
| Status | Retry? |
|---|---|
| 400, 401, 403, 404, 413, 422 | No. The same request will fail again; fix it first. |
429 rate_limited | Yes, after Retry-After seconds. |
429 quota_exceeded, daily_data_limit | Not until the quota or budget resets (month or UTC day). |
| 500, 502, 503, 504, timeouts | Yes, with exponential backoff and jitter, a few times. |
All GET and DELETE calls are safe to repeat. Adding watchlist items is too, because items are keyed by your id. POST /v1/watchlists and POST /v1/webhooks create a new resource each time, so check before retrying them after a timeout.
Responses outside the envelope#
The MCP server uses JSON-RPC errors and tool results with isError: true instead; see MCP protocol errors. Webhook deliveries do not return errors to you; failed deliveries are retried as described in Webhooks.
Handling errors in code#
A small error-aware client
export class DisruptError extends Error {
constructor(status, code, message, retryAfter) {
super(`${status} ${code}: ${message}`);
Object.assign(this, { status, code, retryAfter });
}
}
export async function disrupt(path, init = {}) {
const res = await fetch(`https://app.disruptapi.com${path}`, {
...init,
headers: { Authorization: `Bearer ${process.env.DISRUPT_KEY}`, ...init.headers },
signal: AbortSignal.timeout(30_000),
});
const body = await res.json().catch(() => ({}));
if (res.ok) return body;
const err = body.error ?? { code: `http_${res.status}`, message: body.detail ?? res.statusText };
throw new DisruptError(res.status, err.code, err.message, Number(res.headers.get("Retry-After")) || null);
}from __future__ import annotations
import os
import requests
class DisruptError(Exception):
def __init__(self, status: int, code: str, message: str, retry_after: int | None):
super().__init__(f"{status} {code}: {message}")
self.status, self.code, self.retry_after = status, code, retry_after
def disrupt(method: str, path: str, **kwargs):
resp = requests.request(
method,
f"https://app.disruptapi.com{path}",
headers={"Authorization": f"Bearer {os.environ['DISRUPT_KEY']}"},
timeout=30,
**kwargs,
)
try:
body = resp.json()
except ValueError:
body = {}
if resp.ok:
return body
err = body.get("error") or {"code": f"http_{resp.status_code}", "message": body.get("detail", resp.reason)}
retry = resp.headers.get("Retry-After")
raise DisruptError(resp.status_code, err["code"], err["message"], int(retry) if retry else None)Last updated 2026-11-18. Questions or a mistake on this page? Contact us.