Errors and Retries

The Control Plane returns predictable errors in JSON format:

{
  "error": "...",
  "message": "...",
  "details": { ... }
}

Common response codes

• 400 BadRequest — invalid payload, a required field is missing, or there is a name/format error;
• 401 Unauthorized — the token is missing, expired, or invalid;
• 403 Forbidden — the scope or permissions do not allow the operation;
• 404 NotFound — the resource was not found or is hidden by access policy;
• 409 Conflict / LimitExceeded — a state conflict or a limit has been exceeded;
• 5xx — an internal platform error or a failure while interacting with internal services.

It is also useful to know about OperationDisabled: this is the response you get if you try to use public manual start/stop/scale operations or pass start_immediately / initial_scale where the current managed scenario does not allow them.

How to do retries safely

Safe to retry

• GET requests;
• temporary network errors;
• some 5xx errors, if the operation did not reach the server or did not change state.

Not safe to retry blindly

• destructive operations without checking current state first;
• POST create, unless you have verified that the resource really was not created on the first attempt.

A good retry pattern

1. Execute the write operation.
2. If no response arrives or the connection breaks, do a GET / list first.
3. Verify that the resource is absent or in the expected state.
4. Only then repeat the write operation.

Account for asynchrony

Creating and deleting resources can be asynchronous. That means the object is not required to be in its final state immediately after a successful response. The correct behavior is not to panic, but to read the resource state with GET.