Skip to main content
Every Public API error has the same JSON shape, so one handler covers every call. Use category to decide what to do, and code for the exact cause.

Error shape

Every response carries the same ID in an X-Request-ID header. To tag a call with your own ID, send X-Request-ID: a letter or digit, then up to 127 letters, digits, ., _, : or -. Any other value is replaced with a new ID, not refused.

Categories

Common codes

Getting or updating an incident returns an ETag header, and a PATCH sends that value in If-Match, so two scripts can’t overwrite each other.

Rate limits

Each token has an hourly request quota. The window opens with the token’s first counted call and resets one hour later. If a payment is overdue, the Free quota applies until billing is current. A call counts once its token, workspace, scope and role checks pass, even if it then fails. A 429 counts too; retrying before Retry-After only gets another 429. A call refused with 401, 404 workspace_not_found, 403 scope_missing or 403 permission_missing doesn’t count, and neither does GET /v1/token. A service account call is refused once any of its quotas is full, so adding credentials or service accounts doesn’t add capacity. Spread their load over time instead. Agent runs also spend credits, and a workspace can have 20 pending or running at once. Successful counted responses and 429 responses carry these headers. An error returned while handling a counted call, such as 404, 412 or 422, doesn’t: To stay under the quota, use limit=100 on list calls and slow down before RateLimit-Remaining reaches zero. To ask for more, email support with your organization, the token or service account name (never the token), and your peak requests per hour.

Retry-safe writes

Every POST needs an Idempotency-Key header, and an incident PATCH accepts one: 1–255 letters, digits, - or _. Any other value returns 422 validation_error, with ["header", "Idempotency-Key"] as the field path and string_pattern_mismatch as its code. Generate a new key, such as a UUID, for each new action, and reuse it only when you retry that same action. A key belongs to its caller, workspace and operation, and CloudThinker keeps it for 24 hours. After that, the same key starts a new write. The body is compared byte for byte, so send the exact same bytes when you retry. The CLI sends a fresh key on every write unless you pass your own with --key. Pass the same --key when you retry a write.

Retry a failed call

Retry when the error’s retryable is true, on a 502, 503 or 504 even without a JSON body, and on a network failure, where curl reports status 000. Wait the seconds in Retry-After when the response has it, and double the wait otherwise. Add a little random jitter, and give up after a few tries. Keep the same Idempotency-Key on every try so a write runs at most once:
The CLI doesn’t retry a 429 for you; it exits with code 1. A script that calls it should wait and retry the same way.

API Tokens

See which scope each call needs and fix a 403.

Pricing

Compare plans.