Error codes

The error envelope

The REST API returns every error as a small JSON object with two fields: a stable code you can branch on, and a human-readable message. The portal translates the common failures into user-facing guidance, so you rarely see the raw payload in the dashboard.

{
  "code": "BAD_IMAGE",
  "message": "image must use an immutable tag from an approved source"
}

Status codes

Errors use the HTTP status code plus the code field above.

• 400 (request validation failed). The image, name, resource, or region values were rejected: BAD_JSON, BAD_NAME, BAD_RESOURCES, BAD_IMAGE, BAD_REGION. An image is rejected here, not as a 422, when it is not immutably tagged (never :latest) or is not from the platform registry or an approved base. BAD_REGION means the project's region code is missing or unknown — pick one from GET /v1/regions.
• 401 UNAUTHORIZED. The access token is missing, expired, or invalid.
• 402 INSUFFICIENT_BALANCE (top up your credit with a voucher) or ACCOUNT_NOT_INITIALIZED.
• 403 FORBIDDEN (you may not act on this resource) or ACCOUNT_SUSPENDED.
• 404 NOT_FOUND. The resource does not exist, or it is not yours. For privacy we do not reveal which.
• 409 (conflict with the current state). Examples: a *_TAKEN code when a name is already in use, AUTOSCALING_OWNS_REPLICAS when the replica count is managed by autoscaling and cannot be set by hand, LIFECYCLE_UNSUPPORTED, or REGION_SERVICE_UNAVAILABLE when a service isn't offered in your project's region yet.
• 422 INSUFFICIENT_BALANCE_FOR_AUTOSCALING (not enough credit to raise the maximum replicas), NO_EMAIL (an alert policy needs a verified email address first), or REGION_UNAVAILABLE (the region you chose is real but not open yet — pick an available one or join its waitlist).
• 429 RATE_LIMITED. You are sending requests too quickly. Wait, then retry.
• 503 (a feature is turned off or temporarily unavailable): AI_DISABLED, STRIPE_DISABLED, DB_BACKUP_UNAVAILABLE, REGISTRY_UNAVAILABLE.