Error Codes
Every failure is a structured error object, never a bare exception. It always includes a next_action telling you exactly what to do next.
Rejected before anything runs
These never create an operation and never reserve or charge credits.
| Parameter | Type | Description |
|---|---|---|
INVALID_INPUT | rejected | The input failed validation — malformed email, quote_only not equal to false, or a non-positive max_microcredits. |
IDEMPOTENCY_CONFLICT | rejected | This request_id was already used with different input or a different connection/workspace context. Use a new request_id. |
INSUFFICIENT_CREDITS | rejected | The workspace does not have enough available balance to reserve the price. |
PRICE_LIMIT_EXCEEDED | rejected | The authoritative price is higher than the max_microcredits ceiling you supplied. |
NO_ELIGIBLE_ROUTE | rejected | No approved route for this capability is currently eligible for this workspace. |
RATE_LIMITED | rejected | The workspace hit its daily operation limit. Not retryable until the UTC day resets. |
After a durable operation exists
These include an operation_id. A credit reservation may already exist — replay the same request_id to read the durable outcome rather than starting a new call.
| Parameter | Type | Description |
|---|---|---|
REQUEST_STATE_UNCERTAIN | rejected | Cubeshell could not confirm whether the reservation committed before the connection dropped. Replay the same request_id. |
OPERATION_CONTINUATION_FAILED | failed / unknown | A durable operation was created but its final state could not be confirmed. The provider may have already run. |
PROVIDER_RATE_LIMITED | failed | The upstream provider rate-limited this request. |
PROVIDER_UNAVAILABLE | failed | The upstream provider was unreachable or returned a server error. |
PROVIDER_INVALID_RESPONSE | failed | The upstream provider responded with something Cubeshell could not parse safely. |
UPSTREAM_OUTCOME_UNKNOWN | unknown | The provider outcome is indeterminate. Do not execute this request again — the result is held for reconciliation, not billed. |
UPSTREAM_OUTCOME_RESOLVED_NO_RESULT | unknown | The provider ultimately reported no usable result for this request. |
INTERNAL | rejected / failed | An unclassified Cubeshell-side error. Safe to retry with a new request_id. |
!
Read next_action, not just the code
next_action.type is one of retry_after, poll_operation, change_input, replay_request, or contact_support. It tells you the correct recovery for that specific failure, which can differ even for the same code depending on when it happened.