Error codes - Tinycloud

Every API error carries a stable code, a human message, agent remediation, and a retryability flag.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "...",
    "remediation": "...",
    "retryable": false,
    "requestId": "req_..."
  }
}

Branch on code and retryable. Never on message — messages are written for people and are not part of the contract.

Common codes

Code	Retryable	Means	Do this
`VALIDATION_FAILED`	no	the manifest or request body is not valid	fix the input; `tiny validate` locally
`APPROVAL_REQUIRED`	no	the change widens blast radius in production	approve the deployment, or pass `--yes` if you hold the role
`RESOURCE_LIMIT_EXCEEDED`	no	a quota, row limit, or namespace `maxSize` was reached	paginate, shrink, or raise the quota
`PAYLOAD_TOO_LARGE`	no	object, body, or artifact over its bound	see Limits
`NOT_FOUND`	no	no such object for this token’s organization	check the ID and the token’s organization
`CONFLICT`	sometimes	concurrent modification, or a stale plan digest	re-plan and retry
`APP_ERROR`	no	an unhandled error inside the handler	read `tiny logs`

A cross-organization ID returns 404, not 403 — confirming existence would be a disclosure.

Deployment failure reasons

A failed deployment carries the deployer’s own reason and remediation, and tiny deploy repeats them before exiting non-zero.

Situation	What happened
Health check never passed	the candidate microVM booted but `/_tiny/health` did not answer; traffic never moved
Migration failed	applied before the health check; the previous deployment still serves
Migration contents changed	a previously applied migration was edited — add a new one instead
Build failed	the build VM exited non-zero; the VM is destroyed either way
TAP or nftables creation failed	the deployment fails rather than running unfiltered

A retryable failure retains its current state for idempotent reconciliation. Retrying with the same operation key resumes rather than duplicating.

Target compatibility refusals

These happen at plan time, before any mutation:

Refusal	Cause	Fix
Postgres unavailable	no `TINY_POSTGRES_ADMIN_URL`	configure a cluster, or use `engine: sqlite`
`executesBuildCommands: false`	no build image installed	install one, or drop `build.command`
Egress not permitted	`TINY_FIRECRACKER_ALLOW_EGRESS` unset	enable it, or use a capability
Public apps not allowed	`allowPublicApps` off	an owner must enable it
Memory above ceiling	over 2 GiB	lower `runtime.resources.memory`
Language or type unsupported	Python or `container`	the current target runs TypeScript/JavaScript workers

CLI exit codes

Code	Meaning
0	success
2	command usage
3	authentication
4	validation
5	policy or approval
6	not found
7	interaction required
8	conflict
9	provider or control-plane unavailable

Codes 5 and 7 mean “a human has to do something”, not “this failed”. A script should surface them differently from 4 or 9.

Correlating an error

Every response carries X-Request-Id, and the same value appears in error.requestId. Supply your own X-Request-Id to trace a request across the gateway, the control plane, and the deployment log.

tiny logs my-app --since 1h | grep req_01J...

​Common codes

​Deployment failure reasons

​Target compatibility refusals

​CLI exit codes

​Correlating an error

Common codes

Deployment failure reasons

Target compatibility refusals

CLI exit codes

Correlating an error