Errors - AutoGrowth

Almost every failure carries the same body:

{ "error": "A human-readable message" }

Some failures add a machine-readable code. Two places use a different shape entirely, and both are documented below.

error is a message for a human, not a stable identifier. Log it, show it to an operator, branch on the HTTP status or on code — but do not build control flow on the exact string.

Status codes

Status	When
`400`	The request failed schema validation, or names something unusable — an account not linked to that phone, an account whose platform does not match the automation, a run that is not in a cancellable state
`401`	Missing, malformed, unknown or deleted API key
`402`	The phone’s slot has expired
`403`	Valid key, but the caller is not allowed: insufficient permissions, a disabled user, no organization, or a missing entitlement
`404`	No such row for this key, or no such automation
`409`	The row already exists. Only persona binding creation returns it
`413`	The upload would exceed your organization’s storage allowance
`500`	An unhandled failure. The body is always `{"error": "Internal server error"}`

A request to a path the API does not serve answers 404 with a plain-text body rather than the JSON envelope. If you get text back, the URL is wrong.

Coded errors

Four failures carry a code alongside the message. These are the ones worth branching on, because each has a specific fix and none of them will resolve on a retry.

Code	Status	Meaning	Fix
`MAX_REQUIRED`	`403`	The run is an automation and the organization has no Autogrowth MAX	Buy the licence from the dashboard. It is invite-only, so ask if it is not offered. See Billing
`CREATE_ACCOUNT_ADDON_REQUIRED`	`403`	The create-account automation was scheduled without its paid add-on	Buy the add-on. There is no admin bypass; access is purely payment-based
`SLOT_EXPIRED`	`402`	The target phone’s slot is not active, so nothing can be scheduled on it	Renew the slot for that phone, then schedule again
`STORAGE_LIMIT_EXCEEDED`	`413`	The upload would push the organization over its media allowance	Delete media, or buy extra storage. `GET /content/storage` reports what is used and what is allowed

A typical body:

{
	"error": "Autogrowth MAX is required to run automations.",
	"code": "MAX_REQUIRED"
}

In POST /executions/bulk these codes appear per item instead of on the response. The call answers 201, and each rejected item shows up in failed with its deviceId, an error, and a code when there is one:

{
	"created": [],
	"failed": [
		{
			"deviceId": "0198f8a0-1111-7aaa-8ccc-3e5d7c9b1a24",
			"error": "Device slot has expired. Renew your slot to schedule executions.",
			"code": "SLOT_EXPIRED"
		}
	]
}

Validation failures

A body, query string or path parameter that fails schema validation does not use the { error } envelope. The validator returns its raw result, so you get a 400 shaped like this:

{
	"success": false,
	"error": {
		"name": "ZodError",
		"issues": [
			{
				"code": "invalid_type",
				"expected": "string",
				"path": ["scheduledAt"],
				"message": "Invalid input: expected string, received undefined"
			}
		]
	}
}

The issues array is Zod’s, verbatim, and its exact contents depend on how the value was wrong. Read path to find the offending field. A client that parses error bodies has to handle both this shape and { error }.

Not every 400 is a validation failure. Creating an execution can also answer 400 with a plain { error } — an account that is not linked to the device, an account on the wrong platform for the automation, or a container that has moved or been deleted. Check for error before assuming issues exists.

The upload endpoint’s variant

POST /content/upload is multipart, so its form fields are validated by hand. A field failure answers 400 with a third shape:

{
	"error": "Invalid form data",
	"details": {
		"formErrors": [],
		"fieldErrors": {
			"title": ["Too big: expected string to have <=200 characters"]
		}
	}
}

details is a flattened Zod error: fieldErrors keyed by field name, plus formErrors for anything that did not belong to one field. A request with no file at all answers 400 with { error: "No file provided" } and no details.

401 and 403 are different problems

401 is a credential problem: the header is missing or malformed, or the key matches nothing. Retrying with the same key is pointless, and so is refreshing anything — there is nothing to refresh. 403 is an authorization problem: the key is good, and the user behind it is not allowed to do this. That covers a role without the required permission, a disabled user, a user in no organization, and the two entitlement codes above. Never sign a user out or re-authenticate on a 403; surface it to a human. Full bodies for both are in Authentication.

Not found, or not yours

Most resources are scoped to the key owner. A row that exists but belongs to a teammate answers exactly like a row that does not exist — 404, same message. You cannot tell the two apart, and that is deliberate. The same goes for admin-only automations: GET /automations/{id} answers 404 rather than 403 for a key that may not see them.

What to retry

Situation	Retry?
`500`	Yes, with backoff. Something failed on our side
`401`, `403`, `404`, `409`, `413`	No. Nothing about the request will work next time
`400`	No. Fix the request
`402` `SLOT_EXPIRED`	Only after the slot is renewed

Scheduling is not idempotent. There is no idempotency key, so a create that timed out may or may not have landed — read GET /executions filtered by device and time range before sending it again.

​Status codes

​Coded errors

​Validation failures

​The upload endpoint’s variant

​401 and 403 are different problems

​Not found, or not yours

​What to retry

Status codes

Coded errors

Validation failures

The upload endpoint’s variant

401 and 403 are different problems

Not found, or not yours

What to retry