Error codes
Error families
| HTTP | Family | Recommended handling |
|---|---|---|
| 400 | Validation | Correct the request from the returned field details |
| 401 | Authentication | Replace or refresh the credential |
| 403 | Authorization | Check scopes, membership, module, and workspace |
| 409 | Conflict or drift | Refresh state; regenerate stale plans |
| 412 | Plan precondition | Reinspect and reverify the plan |
| 429 | Rate or quota | Honor retry metadata and reduce request rate |
| 504 | Upstream timeout | Retry only when the operation is safe and idempotent |
SDK callers should branch on the machine-readable error code, not the human message. CLI automation should also check the process exit code and parse JSON output when requested.
See Plans and actions and Billing and limits.