Developer API

Errors produced by the Coasty application return a non-2xx status and a JSON envelope under an error key. The code is stable and safe to branch on; message is human-readable and may change. Every canonical error also carries error.request_id, error.suggestion, and error.docs_url for self-service. The X-Request-Id header identifies the current attempt. X-Coasty-Request-Id can preserve the original operation id on an exact replay, as can the replayed body. A CDN or network intermediary can fail before this envelope exists and return HTML/non-JSON instead. A Link: <url>; rel="help" header mirrors docs_url. Always log the available request ids: they are the fastest way for us to trace a failed call.

Some codes attach machine-readable context to the body. A 402 (INSUFFICIENT_CREDITS) reports required and balance; a 403 reports required_scope and current_scopes; a 422 VALIDATION_ERROR lists the offending field path under error.details; and a 409 state conflict carries current_state with allowed_from or required_state.

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your API wallet does not have enough funds to complete this request.",
    "type": "billing_error",
    "suggestion": "Add funds in the dashboard, or use an sk-coasty-test- key while building (test keys never bill).",
    "docs_url": "https://coasty.ai/docs#errors",
    "required": 5,
    "balance": 2,
    "request_id": "req_8f2c1e9a",
    "retryable": false,
    "retry_with_same_idempotency_key": false
  }
}

Official 503/504 retry policy

For a canonical JSON error, first read retryable,retry_with_same_idempotency_key, retry_after, and code. Parse Retry-After as either delta seconds or an IMF-fixdate HTTP-date. Wait at least the largest valid server delay. If no delay is present, use full jitter: a random delay from zero tomin(30s, 1s × 2^retryIndex).

The recommended automatic client budget is four total attempts (the initial send plus three retries) and a two-minute elapsed budget after the first failure, whichever ends first. This is a client safety default, not a server guarantee. Never violate a largerRetry-After; if it does not fit the foreground budget, stop and requeue the operation for later.

For state reconciliation, use GET /v1/runs/{id},GET /v1/workflows/runs/{id},GET /v1/machines/{id}, orGET /v1/sessions/{id}. For a generic keyed operation whose response was lost, GET /v1/idempotency/{key} can return the stored result or report that it is still processing. A missing record does not prove that an unkeyed or unsupported mutation never ran. Lifecycle actions such as run resume/cancel, workflow update/delete/cancel/resume, machine start/stop/restart/update/delete, and session reset/delete require a resource-state check before any resend.

request_id and Idempotency-Key are different. The client chooses and reuses the idempotency key for one operation; each HTTP attempt gets a current X-Request-Id. Log it, plus any distinct X-Coasty-Request-Id header or body request_id retained from the original operation by an exact replay. If an edge response has none, log UTC time, method, path, andCF-Ray when present. Never copy a request id into the Idempotency-Key header.

Troubleshooting

Five mistakes account for almost every first-week support ticket. Each maps to one status and one fix: