Errors

Errors have an HTTP status and a body like this:

{
  "error": {
    "code": "not_found",
    "message": "ZZZ9 is not on the CBP FIRMS list.",
    "links": { "docs": "https://docs.firmsapi.com/api/errors/#not_found" },
    "details": null
  },
  "meta": { "data_as_of": "2026-10-23", "source": "…", "mode": "live", "request_id": "…" }
}

Match on error.code, not on message; messages may change. links always has docs and sometimes a link that fixes the problem. details is present for some codes.

missing_api_key

401. No x-api-key header. Send your key in x-api-key.

invalid_api_key

401. The key is not a FIRMSapi key, or it does not exist (check for missing characters).

revoked_api_key

401. The key was revoked in the portal. Create a new one. Revocations take effect within a minute.

plan_required

403. Your plan does not include this endpoint (batch and the changes feed need Pro; watchlists need Enterprise). details.plans lists the plans that do. Not counted.

invalid_request

400. A parameter or the body is missing or invalid. details lists each problem as {"field", "problem"}. Not counted.

not_found

404. The code, port or watchlist entry does not exist. Counted, because it is an answer: the code is not on the FIRMS list.

route_not_found

404. There is no such endpoint. Check the path and that it starts with /v1.

quota_exceeded

429. Your plan’s calls, your call packs and your overage cap are used up for this month. links has buy_pack, billing and, on the Free plan, upgrade. See Usage and quotas. Not counted.

index_unavailable

503. The FIRMS data is briefly unavailable (for example, before the first build). Retry with backoff. Not counted.

geocode_unavailable

503. GET /nearby?address= could not reach the address geocoder. Retry with backoff, or pass lat and lon. Not counted.

internal_error

500. Something went wrong on our side. Not counted. Retry with backoff, and quote meta.request_id if it persists.