Skip to main content

Troubleshooting

Use this page as the first-response runbook when API calls fail.

Fast Triage Flow​

  1. Capture endpoint, method, UTC timestamp, request payload (sanitized), and full response body.
  2. Classify the HTTP status (5xx vs 4xx).
  3. Parse Error.Code for 400 responses and apply code-specific handling.
  4. Run availability checks before retrying process/download requests.
  5. Escalate to support if the issue persists.

Classify the Failure First​

5xx​

  • Treat as transient.
  • Retry with exponential backoff (prefer jitter).

4xx​

  • 401 / 403: re-check API key and permissions.
  • 404: verify endpoint path and identifiers.
  • 429: reduce concurrency/rate and retry with backoff.
  • 400: parse Error.Code and fix the request or workflow cause.

For canonical status and code handling, see Error codes.

Validate Availability Before Retrying​

Use availability endpoints to avoid preventable retries:

  • POST /api/satelliteimages/search/available for date discovery.
  • POST /api/satelliteimages/process/composite/available for request-level readiness checks.

See Availability endpoints and Check availability.

Escalate to Support​

If the same failure persists after triage, contact Support and include:

  • endpoint + method,
  • UTC timestamp,
  • sanitized request body,
  • response status + error body,
  • expected behavior vs actual behavior.