Errors and compatibility

Machine-readable failures, limits and retry rules.

REST errors contain a stable machine-readable error string, with optional message and validation issues. Never parse human-readable message text to decide what to do.

HTTP status	Meaning	Client action
400	Malformed JSON, empty body, or invalid query parameters	Correct the request.
401	acquisition_unauthorized: the request is not published yet and queueing an acquisition needs a bearer token	Query published coverage instead, or authenticate.
404	Dataset/tile/request absent or inaccessible under public demo access	Inspect the catalog; do not infer private data existence.
413	Request, row count, date range, or response exceeds a bound	Narrow the query or page size.
415	Incorrect media type on a query POST	Send Content-Type: application/json.
422	Invalid schema, unsupported/incomplete query, or an acquisition the source cannot satisfy (outside_source_coverage, no_cell_centers, dataset_version_pinned)	Inspect issues or call coverage resolution.
503	Data service unavailable	Back off with a bounded retry count.

Coverage resolution returns 200 even when available is false. Its reason is one of coverage_unavailable, request_too_large, no_cell_centers, or unsupported_grid, and acquisitionEnabled says whether /api/v1/data/requests can acquire the miss. No result is silently truncated to make the query succeed.

An acquisition that fails is reported by GET /api/v1/data/requests/{id} with status: "failed" and error.reason. Submitting the same request again within 15 minutes returns that failure; after that it starts a new acquisition.

Reads and direct queries have no purchase side effects. Retry transient failures with exponential backoff and a bounded retry count. Future payment retries will require durable idempotency and reconciliation; they must not automatically re-charge an ambiguous settlement.

The /api/v1 path defines the major version. Clients should accept additive response fields and inspect capabilities for new operations. Removing or changing the meaning of a documented field requires a new major contract. Stable published dataset IDs can be pinned across API calls. The specification’s info.version identifies the contract release.

MCP tools return structured JSON and mark failures with isError. Tool descriptions and input schemas use the same contract as REST. They never expose infrastructure credentials or raw database error details.