Skip to main content

Error Codes

Use this page as the canonical reference for status-level and code-level error handling.

Error Response Shape​

Many 400 responses include structured details:

{
  "Data": {
    "Property": ["Property must <reason>"]
  },
  "Succeeded": false,
  "Error": {
    "Message": "One or more validation errors occurred.",
    "Code": 992
  }
}

Use Error.Code for automation logic and Data for field-level fixes.

Status-Level Handling​

5xx (Transient Server Faults)​

  • Retry with exponential backoff (prefer jitter).
  • Continue until response changes to 2xx or actionable 4xx.

401 / 403 (Authentication/Authorization)​

  • Verify x-api-key, account permissions, and key status.
  • See Authentication.

404 (Not Found)​

  • Re-check endpoint path and request identifiers (GUIDs, dates, AOI references).

429 (Rate or Concurrency Limit)​

  • Back off and retry.
  • Reduce request rate and in-flight concurrency.
  • See Request limits.

400 (Validation or Domain Rule Failures)​

  • Parse Error.Code and apply code-specific handling below.
  • Use Data details to correct payload fields before retrying.

API Error Code Matrix (400 Responses)​

Error codeMeaningRetry guidanceRecommended action
992, 993Request body or parameters are malformed/invalid.No retry until fixed.Correct payload/params using Data validation details.
994Insufficient processing units (download credits) for the request.No retry until units/size change.Add processing units or reduce request size/cost before retrying.
1002No imagery available for area/time.No blind retry.Re-check AOI and dates, then run availability endpoints.
1003Max concurrent requests reached.Retry after backoff.Reduce in-flight requests (see MaxConcurrentConnections).
1004Max area limit reached.No retry until split.Split AOI into smaller requests (see MaxCompositeAreaKm2).
1005Max band count reached.No retry until reduced.Reduce selected bands (see MaxTotalBands).
1006Area/date not covered by an order.No retry until coverage exists.Create or adjust order coverage for requested area/time.
1007Area is within a region without usable data.No blind retry.Do not keep retrying this geometry as-is.
1010Area not fully covered in requested source UTM EPSG.No retry until request change.Adjust order coverage or use UtmDataSelectionMode=combined_utm.
1014Uncertainty data unavailable.No retry until request change.Remove uncertainty band or order data that includes uncertainty.
1020Order exists but image is not predicted yet.Retry later.Treat as delayed availability and retry after time window.
1021Image unavailable due to storage expiration.No retry.Create a new historical order if needed.