Errors and 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`	Credential verification timed out or unavailable, or request timed out.	Check the result before retrying a write.

Failed credential verification grants no stack access and makes no stack changes. An HTTP request still running after the configured deadline returns 503 with message request timed out. The default deadline is 30 seconds. The handler can continue and save a change after this response. 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.

​Status codes

​Retry rules

​Support

Status codes

Retry rules

Support