Ready to deploy? Start Free Trial

Documentation Reference

Error codes

What each error the API answers means, and what to do about it.

Generated

Test the code a refusal carries, never its message: the code is stable, the words may change.

A refusal: {"error": {"code": …, "message": …}}
Refused for a reason of its own: {"error": {"code": …, "message": …, "reason": …}}
Too many requests: Retry-After: 30
Through MCP: A tool error whose data carries the same code.

Any call

Code	Status	Meaning	What to do
`invalid_parameter`	400	A parameter has the wrong type or value; the message names it.	Correct the value and send the request again.
`invalid_request`	400	The request cannot be done as asked; the message says why.	Read the message, correct the request, and send it again.
`unknown_parameter`	400	A parameter the function does not take.	Check the function's parameters in this reference.
`invalid_token`	401	The token is missing, revoked or expired.	Create a token in My Settings → API Tokens, then log in again (cw login).
`access_denied`	403	Your role does not allow this, here.	Ask an admin of the namespace for a role that does, in that environment.
`api_not_available`	403	The API is not open to any of the token's namespaces.	Ask your platform's admin to open the API for your namespace.
`function_not_allowed`	403	The token does not hold this function.	Edit the token in My Settings → API Tokens and tick the function.
`rate_limited`	429	Too many requests: 120 a minute per token, and 10 changes a minute.	Wait the seconds the Retry-After header names, then try again.
`internal_error`	500	Something failed on the platform's side.	Try again; if it keeps failing, contact support.

A call on one record

Code	Status	Meaning	What to do
`not_found`	404	No such record in the token's namespaces — or no such function on this platform.	List the records first to find the id; an older platform may not offer the function yet.

A list

Code	Status	Meaning	What to do
`namespace_not_found`	404	The token has no such namespace.	Use a code that cw namespaces (or whoami) lists.

Any change

Code	Status	Meaning	What to do
`writes_disabled`	403	Changes through the API are not open to this account.	Ask your platform's admin to open them (Platform → Customer API).
`request_in_progress`	409	The first request with this Idempotency-Key is still running.	Wait a moment, then send it again with the same key.
`idempotency_key_reused`	422	This Idempotency-Key was used for a different request.	Use a new key for a new change.
`locked`	423	The platform's safety lock holds runs right now.	Try again later.
`idempotency_key_required`	428	A change needs an Idempotency-Key header.	Send a new unique key with each change, and the same key when you retry it.

The functions that name them

Code	Status	Meaning	What to do
`missing_parameter`	400	A required parameter is missing.	Send it: this reference marks it required.
`plan_required`	403	The project's plan does not include this.	Upgrade the project's plan, or ask the namespace's admin.
`not_a_change`	405	This function reads: it is asked with GET, not POST.	Send it as a GET.
`in_progress`	409	Something runs on the app, and the change would cut it short.	Wait for it to finish (cw runs --app), then try again.
`not_deployed`	409	The app has not been deployed yet, so there is nothing to change.	Deploy it first, from the dashboard.
`not_retryable`	409	The run cannot be retried; reason says why (a newer run, its queue, nothing failed…).	Follow the reason: retry the newer run, or start the change again.
`retry_coming`	409	An automatic retry of this run is due in minutes.	Wait for it, or retry now with now: true.
`upgrade_standby`	409	A version upgrade holds the app.	Finish or cancel the upgrade in the dashboard first.
`unavailable`	503	The platform cannot answer this right now (a service it reads is down).	Try again in a few minutes.

Was this page helpful?

Your answer helps us prioritize documentation improvements.