Errors

Synchronous errors (4xx / 5xx)

Immediate error responses (e.g. invalid request, auth failure) share the same envelope:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credit balance"
  }
}

Asynchronous job failures

When a job transitions to failed, the error details are returned as flat fields on the Get job status response:

{
  "job_id": "351e635d-7c25-4ae8-a2a5-60c01a6f434c",
  "status": "failed",
  "created_at": "2026-03-12T15:00:00Z",
  "completed_at": "2026-03-12T15:31:15Z",
  "result_path": null,
  "error_code": "VALIDATION_ERROR",
  "error_message": "Polygon area (52.6 km²) exceeds 50 km² limit for endpoint 'timeseries'"
}

For 5xx failures, error_message returns a fixed string to avoid leaking internal details. The string depends on the cause, because the action you should take differs:

`error_code`	`error_message`
`EXTERNAL_SERVICE_ERROR` (502)	`The analysis could not be completed due to a temporary issue with an external satellite data service. Your credits have been automatically refunded. Please try again later.`
`TIMEOUT` (504)	`The analysis could not be completed in time. Your credits have been automatically refunded. Please try again later.`
Anything else	`An internal error occurred. Please try again later or contact support.`

Error codes

HTTP	Code	Meaning	Recommended action
`400`	`VALIDATION_ERROR`	Invalid request body, bad parameter, or a per-endpoint cap exceeded — polygon area (`newbuilding` / `disappearbuilding` ≤ 30,000 km², `timeseries` ≤ 50 km²) or date range (`timeseries` ≤ 3 years). Rejected before credits are consumed.	Fix the request. Do not retry unchanged.
`401`	`UNAUTHORIZED`	Missing, malformed, or revoked API key.	Check `Authorization` header.
`402`	`INSUFFICIENT_CREDITS`	Not enough credits for the job.	Purchase credits in the Console.
`403`	`FORBIDDEN`	Key lacks permission for this endpoint.	Check plan entitlements.
`404`	`NOT_FOUND`	Job ID does not exist.	Verify the UUID.
`404`	`SCENE_NOT_FOUND`	No Sentinel-1 scene within ±14 days of the requested date.	Widen date range or pick another date.
`404`	`INSUFFICIENT_SCENES`	Fewer than two usable scenes found for `newbuilding` / `disappearbuilding` / `timeseries`, or the available scenes lack the orbit metadata needed to compare them.	Widen the date range.
`410`	`GONE`	Result file is past the 30-day retention window.	Result is unavailable; resubmit if needed.
`429`	`RATE_LIMIT_EXCEEDED`	Request rate or concurrent-job limit exceeded.	Back off exponentially.
`500`	`INTERNAL_ERROR`	Unexpected server error.	Retry with backoff; contact support if persistent.
`502`	`EXTERNAL_SERVICE_ERROR`	Upstream satellite-data provider error. Credits are refunded automatically.	Retry after a few minutes.
`504`	`TIMEOUT`	Request timed out. Credits are refunded automatically.	Retry with backoff.

Using an SDK?

The Python and JavaScript SDKs raise typed exceptions for each status code above — for example 402 becomes InsufficientCreditsError and a failed job becomes JobFailedError.

Warnings are not failures. A job that returns warnings has status: "completed" and error_code: null, and the result is available as usual. They tell you that the imagery the API selected differs from what you asked for, so you can decide whether to trust the result or adjust the request.

They appear in the warnings array of Get job status. Preview a request returns the two that can be determined before submission: LOW_AOI_COVERAGE and CREDITS_NOT_ESTIMABLE.

Code	Meaning	Recommended action
`SCENE_DATE_FAR_FROM_REQUESTED`	A scene used is 60 days or more away from the date you requested. The exact gap is not reported — compare `scene_selection.first_month` / `last_month` with your requested dates.	Suitable imagery may not exist near your dates. Widen or shift the date range.
`PERIOD_PARTIALLY_COVERED`	The observations span less than 80% of the requested period. The percentage in the message is rounded down to the nearest 10%.	Split the period into shorter requests, or accept the narrower span.
`LOW_AOI_COVERAGE`	The imagery covers less than 90% of your AOI.	Part of the AOI has no data. Shrink or shift the AOI.
`FEW_CANDIDATE_SCENES`	Only the bare minimum number of scenes was available.	Widen the date range for a more reliable result.
`ALTERNATIVE_GROUP_AVAILABLE`	Other imagery covers a later part of the requested period, but could not be combined with the imagery used.	Split the period into separate requests to analyse both parts.
`SCENE_METADATA_INCOMPLETE`	Some candidate scenes were excluded because required orbit metadata was missing.	Usually safe to ignore. Contact support if results look wrong.
`CREDITS_NOT_ESTIMABLE`	Returned only by Preview a request: the credit cost depends on the extent of the selected scene, which is not known before submission. `credits.estimated` is `null` — this does not mean the job is free.	Use `polygon` input if you need a pre-submission estimate.

Change detection compares scenes captured from the same viewing geometry. When your period spans imagery from different orbits, one request cannot cover all of it — this is the usual cause of PERIOD_PARTIALLY_COVERED and ALTERNATIVE_GROUP_AVAILABLE.

Retrying safely

Idempotent GETs (GET /api/v1/jobs/*) — safe to retry unconditionally.
POST detection requests — if you receive 5xx or a network error without a response, check whether a job_id was created before retrying to avoid duplicate jobs.
Use exponential backoff (start 1 s, cap 30 s, max 5 attempts) for 429, 5xx, and 504.

Tracing a failed job

If a job transitions to failed:

Call Get job status to read error_code and error_message.
Map error_code to the table above for recommended actions.
Surface error_message to the end user where appropriate.

The error field is deprecated and returns the same value as error_code. Use error_code + error_message in new integrations.

Failed jobs do not consume credits.

Synchronous errors (4xx / 5xx)

Asynchronous job failures

Error codes

Warnings

Retrying safely

Tracing a failed job

Next steps

Authentication

Rate limits

How it works

On this page