Errors and limits

Error format

Gateway errors use a versioned JSON envelope. Use error.code for programmatic handling and error.message for a readable description.

retryable indicates whether an unchanged request may succeed later. details provides error-specific information, such as completed pipeline steps or an exceeded budget. Query-limit errors include numeric limit and value fields. Validation errors include issues with field paths and descriptions.

{
  "error": {
    "version": "1",
    "code": "PIPELINE_STEP_FAILED",
    "message": "filter needs by, op and value.",
    "requestId": "01J8Z2K9V0QK2W5S6M4T1P3RXA",
    "retryable": false,
    "issues": [{ "level": "error", "path": "bad", "message": "filter needs by, op and value." }],
    "details": { "completedSteps": [{ "id": "kept", "op": "limit", "count": 2 }], "failedAfter": 1, "totalSteps": 2 }
  }
}

The x-request-id response header identifies the request. For gateway errors it matches error.requestId. Include this ID in support requests. MCP tools may also expose the error under structuredContent.error; always check isError and the returned content.

Upstream and edge responses may use a different format. Check HTTP status and content type before parsing, and discard incomplete streamed responses.

All error codes

Authentication failures

Send exactly one credential using Authorization: Bearer. Check for whitespace or a truncated value. A rotated key stops working immediately, while a scheduled cancellation can remain active until the paid period ends.

Do not retry 401 or 403 responses unchanged. Check your key and subscription. A support reference is not an API credential. For legacy integrations, the client guide lists accepted credential locations.

Query and stream errors

Reduce the bounding box, filter tags earlier, or request centers rather than full geometry when responses are too large. Set timeout and memory explicitly within the plan ceilings. Historical date, changed, and newer selectors are not supported.

RESPONSE_TOO_LARGE names the response-limit condition, but a streamed response that exceeds its cap can close without a fresh JSON error envelope. Treat truncated JSON, XML, or CSV as a failed request, even if you first received HTTP 200.

UPSTREAM_TIMEOUT uses HTTP 502. Edge timeouts may have a different status and response format.

Retry handling

1. Do not retry invalid credentials or invalid query settings without changing them.
2. For 429, check the code. Rate and concurrency limits can clear quickly; allowance exhaustion does not clear until the reported reset, a cap/policy change, or an upgrade. Explorer’s total limit does not reset.
3. Honor Retry-After, then use exponential backoff with jitter for transient service failures. Cap the number of attempts.
4. Reduce expensive queries after timeouts instead of immediately replaying them.
5. Do not automatically retry checkout, key rotation, or a signed payment as if it were a read-only request.

// Retry-After can be seconds or an HTTP date.
function retryDelayMs(value) {
  if (!value) return null;
  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
  const date = Date.parse(value);
  return Number.isFinite(date) ? Math.max(0, date - Date.now()) : null;
}

Reporting a failure

Include the request ID, approximate UTC time, endpoint name, and error code. If relevant, share a minimal query after removing sensitive details. Never send an Authorization header, API key, payment signature, or full keyed URL.

Check service status and the usage dashboard first for a known outage or exhausted allowance.