Errors, Redirects, and Retries

This guide covers the client behavior that causes the most avoidable integration failures: status-code handling, redirect handling, and retry decisions.

Redirects

The API returns 302 Found when a redirect is appropriate. Typical causes are:

1. Using http:// instead of https://
2. A path mismatch, usually because of a trailing slash difference

Why this matters

Many HTTP clients follow redirects automatically and may change the request method. That can turn a real URL issue into a misleading downstream error.

Recommendation

• use the correct host and versioned public path from Authentication and Regions
• match the documented path exactly, including trailing slashes
• disable automatic redirect following while debugging

response = requests.post(
    url,
    json=payload,
    headers=headers,
    allow_redirects=False,
    timeout=30,
)

if response.is_redirect:
    raise RuntimeError(
        f"Unexpected redirect {response.status_code} -> {response.headers.get('Location')}"
    )

curl -sS -o /dev/null -w "%{http_code}\n" --max-redirs 0 "https://YOUR_API_HOST/..."

Status code model

Use the HTTP status code first, then parse the response body for details:

Code	Meaning	Recommended action
2xx	Request succeeded	Continue the workflow and persist returned identifiers.
400	Invalid request body or parameters	Validate request shape, required fields, and workspace-specific ids.
401	Missing or invalid credentials	Check client-id, client-secret, and environment configuration.
403	Authenticated but not allowed	Confirm workspace access, role, permissions, and optional user-email.
404	Resource not found or not visible	Validate region, path, API version, workspace, and identifiers.
409	Conflicting resource state	Re-fetch current state before attempting another write.
429	Rate limited	Back off and retry with jitter.
5xx	SpotDraft or upstream infrastructure issue	Retry with bounded backoff when the operation is safe to retry.

Retry model

Retry only when the failure is likely transient and the operation is safe to repeat.

Good retry candidates:

• 429
• network timeouts
• temporary connection errors
• selected 5xx responses

Poor retry candidates:

• malformed request payloads
• missing required fields
• invalid credentials
• permission failures
• not-found errors caused by wrong region, path, or workspace

Use exponential backoff with jitter, cap the total retry window, and route exhausted retries to a queue, dead-letter path, or manual review workflow.

Error logging

Log enough context to reconstruct the failed request without exposing secrets:

• regional host and endpoint path
• method and status code
• internal request id or job id
• workspace or environment
• external metadata keys involved
• retry count
• response body when it does not contain secrets

For endpoint-specific error bodies and response schemas, use the API reference.