Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

Skip to main content

GDELT Cloud home page

Data Reference

Copy page

Search...

GDELT Cloud home page

Search...

Navigation

The surface

Error reference

The surface

Error reference

Every code the v2 API returns, what it means, and what to do about it.

Every error carries a stable code. Branch on the code, not the HTTP status and not the message — the status is shared across unrelated failures and the message is prose we may reword. Where a finite set of legal values exists, the body carries it in details.accepted_values, so a 400 is usually enough to fix the call without reading anything.

​

Authentication

The request never reached a handler. Check the key, not the query.

Code	HTTP	What happened	What to do
MISSING_API_KEY	401	No Authorization header was sent.	Send Authorization: Bearer gdelt_sk_….
INVALID_API_KEY	401	The key is not recognised.	Check for a truncated paste; create a new key if unsure.
INVALID_TOKEN	401	The bearer token is malformed or expired.	Re-issue the token.
API_KEY_DISABLED	403	The key was disabled — usually by the automated abuse sweep.	Check the owner mailbox for the notice, then create a replacement key.
ADMIN_REQUIRED	403	An admin-only preview surface.	Not available on customer keys.

​

Entitlement

The endpoint exists and your key is valid, but this workspace does not carry the flag it needs. Always an explicit error — never an empty result, which would be indistinguishable from “we have no data for you”.

Code	HTTP	What happened	What to do
PLAN_REQUIRED	403	The endpoint is behind an entitlement this workspace does not carry. The body names the flag.	Read details.required_flag; that flag is what has to be enabled for this workspace.
BRIEF_ACCESS_DENIED	403	Briefs are not enabled for this workspace.	Requires can_use_briefs.
DETAILED_BRIEF_NOT_AVAILABLE	403	The requested brief depth is not enabled.	Request a shallower depth, or enable can_use_detailed_briefs.
PAYMENT_OVERDUE	402	The workspace is past due and reads are paused.	Settle the balance; access resumes without a new key.

​

Validation

A parameter was rejected rather than silently ignored. A filter that looks accepted and does nothing produces a confident, wrong answer, so the API fails loudly instead. The body carries details.accepted_values wherever a finite set exists.

Code	HTTP	What happened	What to do
UNKNOWN_PARAM	400	A strict descriptor-backed endpoint received a query parameter it does not declare.	Read details.param, details.did_you_mean and details.accepted_params; correct or remove the parameter.
UNSUPPORTED_FILTER	400	A parameter this endpoint deliberately does not support. Rejected rather than ignored.	Read details.alternatives — the reference lists a replacement for every rejected parameter.
INVALID_CURSOR	400	The pagination cursor could not be read. Cursors are opaque — construct them only by copying pagination.next_cursor.	Restart the walk from the first page and follow pagination.next_cursor.
CURSOR_STALE	400	The cursor is valid but no longer describes this result set: it was issued against a pre-built daily snapshot, and this request is either being answered live or against a snapshot that has since been rebuilt. Continuing would repeat some rows and skip others, so the request is refused rather than answered plausibly. details.reason is row_source_changed or snapshot_rebuilt.	Restart the walk from the first page. A walk that must not be interrupted can pin itself to the live path by including a filter only the live path answers, such as sort=recent.
UNSUPPORTED_PARAM	400	A parameter that is not part of this endpoint at all.	Check the parameter reference for the endpoint you are calling.
INVALID_DATE	400	A date is not YYYY-MM-DD.	Use ISO dates. Times are not accepted on date parameters.
INVALID_DATE_RANGE	400	date_start is after date_end.	Swap them.
DATE_WINDOW_TOO_LARGE	400	The window exceeds this endpoint’s maximum span.	Narrow the window and page through it. Unbounded scans are refused, not served slowly.
DATE_RANGE_REQUIRED	400	This endpoint will not run unbounded.	Pass days or an explicit date_start/date_end.
INVALID_LIMIT	400	limit is outside the accepted range.	Use the documented maximum and paginate with cursor.
INVALID_BBOX	400	A bounding box is malformed or inverted.	The axis order differs by family, and a swapped box usually returns an empty or wrong 200 rather than this error. Events, stories, facilities and energy take latitude first — lat_min,lon_min,lat_max,lon_max. Maritime takes longitude first — min_lon,min_lat,max_lon,max_lat. The per-parameter description in the spec is authoritative for the path you are calling.
INVALID_NEAR	400	The near grammar does not match this endpoint’s.	Events and stories take lat,lon with a separate radius_km; facilities and energy take a single lat,lon,radius_km triple. The spec carries the right example per path.
INVALID_ENTITY_ID	400	A bare name was sent where a resolved id is required.	Resolve it first with GET /api/v2/search, then pass the e_… id.
AMBIGUOUS_LEGACY_ID	409	A legacy facility-unit id maps to more than one canonical physical site.	Use a canonical s_… site id returned by GET /api/v2/facilities; candidate ids are in details.canonical_site_ids.
ENTITY_REQUIRED	400	This endpoint is per-entity and no entity was named.	Pass entity.
FILTER_REQUIRED	400	This endpoint needs at least one narrowing filter.	Add a geography, taxonomy or entity filter.
INVALID_LIST_SOURCE	400	An unknown screening list, or one we declare but do not yet carry.	Branch on details.reason: unknown_source_key vs declared_but_not_ingested. Never an empty success — on a sanctions surface that would read as a clean result.
EVENT_FAMILY_CATEGORY_CONFLICT	400	A deprecated event_family contradicts the category sent with it.	Drop event_family; category implies the family.
SUBCATEGORY_REQUIRES_CATEGORY	400	subcategory was sent with no category. Sub-event types are scoped by category and several labels are ambiguous without one.	Send category too. details.accepted_categories lists the categories that have subcategories.
INVALID_SUBCATEGORY_FOR_CATEGORY	400	The subcategory is a real taxonomy code but not one that belongs to the category sent with it.	Read details.accepted_values — it is the subcategory list for the category you actually asked for.
STORY_CATEGORY_CONFLICT	400	story_category and the deprecated category spelling of it were both sent, naming different values.	Send one. story_category is the current spelling.
INVALID_NUMBER_RANGE	400	A metric _min is greater than its _max, so the range is empty. Refused rather than served as a (correct but useless) empty result.	Read details.min_value / details.max_value and swap them.
EVENT_FAMILY_METRIC_CONFLICT	400	A metric only one event family publishes (magnitude, systemic_importance, propagation_potential, market_sensitivity — all CAMEO+) was combined with a taxonomy filter that commits the request to the other family. Unsatisfiable by construction: the conflict detail table has no such column.	Read details.metric_family and details.implied_family — they disagree. Drop the metric filter, move the taxonomy filter into details.metric_family, or use a metric both families publish (details.accepted_metrics_for_family).

​

Data availability

The request is valid, but the evidence required to answer it under the requested semantics is not available. Never interpret this as an empty result or as evidence that nothing happened.

Code	HTTP	What happened	What to do
ENTITY_ATTRIBUTION_UNAVAILABLE	503	Material entity attribution is unavailable for the requested window, so the API refuses to substitute broad story co-occurrence.	Retry later or use a window with ready attribution. Send entity_match=coverage only if broad co-occurrence is the question you intend to ask.

​

Not found and withdrawn

The id is well-formed but resolves to nothing, or to something that has since been superseded. A withdrawn or merged record returns a pointer to its replacement rather than a bare 404.

Code	HTTP	What happened	What to do
NOT_FOUND	404	No record with that id.	Ids are opaque — do not construct them. Re-fetch from a list endpoint.
NOT_FOUND_IN_WINDOW	404	The id resolves to nothing INSIDE the date window the request asked for. It may exist outside it.	Drop start_date/end_date — a by-id read defaults to the record’s own date — or widen the window.
ENDPOINT_REMOVED	410	A retired endpoint. It existed, it is intentionally gone, and it will not return.	Read details.replacement — it names the /api/v2 path that answers the same question. The Link: rel="successor-version" header carries it too.
ENTITY_NOT_FOUND	404	The entity id does not resolve.	It may have merged; re-resolve the name through GET /api/v2/search.
STORY_MERGED	404	The story was adjudicated a duplicate and folded into another.	Follow the replacement id in the body. This is not an error to retry.
EVENT_WITHDRAWN	404	The event stopped resolving and no single replacement could be determined — it was suppressed in review, or merged in a way that names no one live successor.	Read the reason in the body; do not treat the prior record as still true. Re-query GET /api/v2/events for the current event covering this incident.
EVENT_MERGED	404	The event was adjudicated a duplicate and folded into another event, which is live.	Follow successor_event_id in the body. This is not an error to retry.

​

Limits

The request was well-formed and refused on volume or account state.

Code	HTTP	What happened	What to do
RATE_LIMITED	429	Too many requests per minute.	Back off and retry. Concurrency, not volume, is usually the cause.
QUOTA_EXCEEDED	429	The Query Unit allowance for the period is spent.	Wait for the period to roll over, or raise the allowance for this workspace.

​

Server

Our fault. Safe to retry with backoff.

Code	HTTP	What happened	What to do
INTERNAL_ERROR	500	An unhandled failure.	Retry with backoff. If it persists, send us the request id from the response.
PLAN_FEATURES_ERROR	500	Entitlements could not be resolved for this workspace.	Transient — retry. Not a statement about what your workspace carries.
ORG_RESOLUTION_ERROR	500	The workspace behind the key could not be resolved.	Transient — retry.
SEMANTIC_SEARCH_UNAVAILABLE	503	The embedding call behind search= failed or timed out, so the query could not be embedded. Nothing is served in its place — a lexical fallback would silently answer a different question.	Retry shortly. To proceed without it, drop search and narrow with category, country or entity instead.

​

Rejected values, by vocabulary

A closed vocabulary rejects anything outside its list. Most return INVALID_ENUM; a few carry their own code so a caller can branch without inspecting details. Derived from the same vocabulary registry the server validates against.

Code	Vocabularies
INVALID_CATEGORY	event_category
INVALID_CONTINENT	continent
INVALID_ENUM	actor_role, actor_type, atlas_coverage_tier, atlas_gpr_component, atlas_gpr_construction, atlas_gpr_metric, atlas_gpr_variant, atlas_level, atlas_posture_scope, atlas_posture_window, atlas_weighting, brief_audience and 55 more
INVALID_LIST_SOURCE	exposure_list, list_source_key
INVALID_REGION	region
INVALID_TRACKER	gem_tracker
UNSUPPORTED_FILTER	gem_heavy_industry_tracker

An observed vocabulary never rejects on membership — it is a dated measurement, not an allowlist, and the API accepts values outside it. Only closed vocabularies appear above.

⌘I