Errors and retries

HTTP status codes, request tracing, and safe manager API retries.

Every manager error uses this JSON envelope:

{
  "code": "invalid_request",
  "message": "invalid request body",
  "request_id": "d28e1ad4-2ca8-4f35-b590-8bf3b53abc81"
}

code is the machine-readable error category. message describes the failure. request_id matches the response’s X-Request-Id header. Validation errors do not include a field-by-field details array.

Status codes

HTTP status	Code	Meaning	Next step
400	invalid_request	Invalid JSON, configuration, pagination, stack UUID, or creation key.	Correct the request.
401	unauthorized	Missing or invalid manager credential, or unusable manager identity.	Check the Bearer header. Contact MyStacks if your issued key still fails.
404	not_found	Stack is missing or belongs to another manager. Also used for unknown routes.	Check the path and stack ID.
409	conflict	A creation key was reused with different input.	Reuse the original input or choose a new key for an intended new stack.
413	payload_too_large	Body exceeds 262,144 bytes.	Reduce the body size.
429	rate_limited	API-key verification was rate limited.	Wait before retrying.
500	internal_error	Unexpected failure or a conflicting saved manager identity.	Keep the request ID. Contact MyStacks if the failure persists.
503	service_unavailable	API-key verification timed out or is unavailable.	Wait before retrying.

Failed credential verification grants no stack access and makes no stack changes. The manager API does not publish a fixed requests-per-second limit or a Retry-After header contract.

Retry rules

• Reads: Retry temporary failures with a bounded delay that increases between attempts.
• Create: Reuse the same Idempotency-Key and original input after a timeout or lost response.
• Update: Read the stack after an uncertain result. A retry creates another revision and can overwrite later edits.
• Invalid input or credentials: Correct the cause before retrying.

See creation idempotency and update ordering for the full rules.

Support

Send MyStacks the HTTP method, endpoint path, status code, and X-Request-Id. Never include the API key in a support message.