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"
  }
}
  • Branch on error.code, not on message. Messages are for people and may be reworded.
  • details appears only on invalid_request from validation.
  • Rate-limit and quota headers are sent on errors too. See Rate limits.

Error codes#

CodeHTTPMeaningFix
invalid_request422The 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_large400limit 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_limit400limit is below 1. Out-of-range values are usually caught earlier as invalid_request.Send a limit of at least 1.
invalid_failure_layer400failure_layer on GET /v1/forecast is not a known layer.Use an id from GET /v1/failure-layers.
invalid_items400A 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_webhook400The 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_key401No Authorization: Bearer or X-API-Key header.Send your key. See Authentication.
invalid_api_key401The 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_required403The plan does not include exposure checks. Every current plan does, so you should not see this.Contact us if you do.
not_found404No 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_large413The request body is over 2 MB.Split large exposure checks or item uploads into several calls.
rate_limited429Your 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_exceeded429The 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_limit429The 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_error500Something failed on our side.Retry with backoff. If it persists, contact us with the time and endpoint.

Which errors should I retry?#

StatusRetry?
400, 401, 403, 404, 413, 422No. The same request will fail again; fix it first.
429 rate_limitedYes, after Retry-After seconds.
429 quota_exceeded, daily_data_limitNot until the quota or budget resets (month or UTC day).
500, 502, 503, 504, timeoutsYes, 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);
}

Last updated 2026-11-18. Questions or a mistake on this page? Contact us.