Errors

Errors use a consistent JSON envelope:

{
  "error": {
    "status": 422,
    "code": "unprocessable_entity",
    "message": "Unprocessable entity.",
    "details": [
      { "code": "invalid_value", "param": "site_id", "message": "Site not found." }
    ]
  }
}

status is the HTTP status, code is the stable machine-readable category, message is a human-readable summary, and details contains field-level or business-rule information when available.

Error categories

bad_request

The request is structurally invalid or is missing a required value. Fix the request before retrying.

unauthorized

The bearer token is missing, malformed, or invalid. Check the Authorization header and rotate the token if necessary.

forbidden

The account is authenticated but inactive or lacks access to the resource.

not_found

The requested site, snapshot, task, or other resource does not exist or is not available to the account.

conflict

The requested action conflicts with the resource’s current state—for example, another background operation is already running. Inspect the task or current resource state before retrying.

unprocessable_entity

The request is well-formed but violates a product rule. Read details[].param and details[].code to decide what to change.

too_many_requests

The account has exceeded its rate limit. Follow the rate-limit guidance.

service_unavailable

An upstream or temporary provider failure occurred. Retry with bounded exponential backoff when the operation is safe to repeat.

Retry rule of thumb

Retry only transient failures (429, 503, and documented conflicts) and only when the operation’s side effects are understood. For a background operation, prefer retrieving the existing task over starting a second operation.