Errors - Clatter Labs Docs

Errors are JSON with a stable code and a human-readable message:

JSON

{ "error": { "code": "out_of_credits", "message": "You're out of Clatter Labs credits. ..." } }

Status	`code`	Meaning	What to do
400	`bad_request`	Missing `input`, or a bad `tier`	Fix the request
401	`invalid_api_key`	The key is wrong or revoked	Check the key, or create a new one
401	`missing_account_id`	No `X-Clatter-Account` header	Send your Account ID
401	`account_mismatch`	The Account ID doesn't own this key	Use the key owner's Account ID
402	`out_of_credits`	Your credit balance is used up	See Credits
403	`insufficient_scope`	The key lacks the permission	Create a key with that permission
403	`early_access`	Your account isn't in the early-access program yet	Ask for access
403	`no_cloud_account`	Your account hasn't been set up for Cosmos Agent	Sign in once to a Cosmos Agent app with this account, then retry. If it persists, visit the Help Center
403	`account_suspended`	Your account is paused for 24 hours under the Abuse policy	Wait until `resets_at` (`Retry-After` seconds), or appeal through the Help Center
404	`not_found`	No run with that id on your account	Check the id
405	`method_not_allowed`	Wrong HTTP method	See the endpoint's reference
413	`too_large`	`input`, `metadata` or the body is too big	See Limits
429	`rate_limited`	Over the key's requests per minute	Wait `Retry-After` seconds
429	`too_many_runs`	5 runs already in progress	Wait for one, or cancel one
502	`upstream`	Cosmos Cloud didn't answer	Retry with backoff
503	`unavailable`	The key couldn't be checked right now	Retry with backoff

Runs that fail

A run that starts but can't finish ends with status: "failed" and an error:

JSON

"error": { "code": "out_of_credits", "message": "You're out of Clatter Labs credits." }

code is out_of_credits when the balance ran out midway, otherwise run_failed.

Successful keyed responses carry X-RateLimit-Limit and X-RateLimit-Remaining. A 429 adds Retry-After (seconds).