Errors

Available now Every 4xx and 5xx response from api.satellitedata.net/v1 is a problem document (RFC 9457) with media type application/problem+json.

{
  "type": "https://docs.satellitedata.net/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No item S2C_T15TVK_20260714T170911_L2X in collection sentinel-2-l2a.",
  "instance": "/v1/collections/sentinel-2-l2a/items/S2C_T15TVK_20260714T170911_L2X",
  "code": "not-found",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D"
}

Members

Member	Meaning
type	A URL under https://docs.satellitedata.net/problems/. The page explains the cause and the fix. Stable for the life of /v1.
title	A short summary that does not change between occurrences.
status	The HTTP status, repeated for clients that lose the status line.
detail	What went wrong this time, naming the value at fault.
instance	The request path.
code	The last path segment of type. Switch on this in code.
requestId	The request id, also sent as X-Request-Id. Errors raised by the gateway in front of the API (a bad key, rate limits, timeouts) carry it only here, not as a header. Quote it when you ask for help.

Optional members appear when they help: errors (a list of pointer and detail pairs for validation failures, where pointer is a JSON Pointer into the body or a query parameter name), retryAfter, limits (the limit and the value requested) and unitsEstimated.

Clients must ignore members they do not know; new ones may be added.

Routes that are not available yet

Routes from the full contract that lean v1 does not serve answer 404 with code not-found and a detail saying there is no such route or method in lean v1. Check the detail instead of treating every 404 as a missing resource.

Codes

Each code has its own page. Codes marked as later belong to features that are not built yet.

Status	Codes	When
400	invalid-parameter, invalid-body, invalid-filter, zoom-out-of-range, invalid-token-request, invalid-mcp-message, invalid-process-graph	The request is malformed
401	invalid-key, invalid-client	Missing or bad credentials
403	email-unverified, insufficient-scope, key-suspended, origin-not-allowed	Valid credentials, not allowed here
404	not-found, unknown-collection, mcp-session-expired	No such resource
409	key-limit	The account already has its maximum keys
413	output-too-large, body-too-large	A size cap was exceeded
422	unknown-band, harmonize-unavailable, units-unavailable, too-many-scenes, area-too-large, request-too-expensive, budget-exceeded	Valid JSON the API cannot serve
429	rate-limited, concurrency-limit, quota-exhausted, ip-rate-limited	A limit was hit
500	internal	A bug; logged
503	upstream-unavailable, maintenance	An upstream source or the service is down
504	render-timeout	A render ran past 29 seconds

A 503 caused by an upstream outage names the upstream, such as Earth Search, so you can tell their failure from ours.

Retrying

• Retry 429, 503 and 504, with exponential backoff and jitter. Honour Retry-After when it is present; it is in seconds.
• Do not retry other 4xx responses unchanged. Fix the request using detail and errors.
• In lean v1, per-second and monthly limits are enforced by API Gateway’s usage plan and answered as problem documents (rate-limited, quota-exhausted); see Limits and quotas.

Older hosts

stac.satellitedata.net and tiles.satellitedata.net do not use problem documents. Missing keys get API Gateway’s 403 Forbidden, and the download API returns a JSON body with a detail member. See Older hosts.