Errors

Synchronous errors (4xx / 5xx)

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

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your credit balance is insufficient. Please purchase more credits."
  }
}

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:

An internal error occurred. Please try again later or contact [support](mailto:console-support@spcsft.com).

Error codes

HTTP	Code	Meaning	Recommended action
`400`	`VALIDATION_ERROR`	Invalid request body, bad parameter, or polygon area exceeds the per-endpoint cap (`newbuilding` ≤ 30,000 km², `timeseries` ≤ 50 km²). 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 scenes found for `newbuilding`/`timeseries`.	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.	Retry after a few minutes.
`504`	`TIMEOUT`	Request timed out.	Retry with backoff.

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.