Error codes
Every failure has the same shape: a stable code, a message, a remedy where one exists, a docs_url that points at the entry below, and a request_id. Branch on the code. The message can change.
All codes
invalid_requestHTTP 400
The call was malformed: a missing field, a wrong type, or a value the platform refuses.
Read message for the field, correct it and resend. Retrying the same body will fail the same way.
Retry: after fixing
unauthenticatedHTTP 401
No key was sent, or it is wrong, revoked or expired.
Send Authorization: Bearer hlm_sk_.... An MCP client that supports OAuth can sign in again from the www-authenticate header.
Retry: after fixing
insufficient_scopeHTTP 403
The key is valid but lacks the scope this operation needs.
Call whoami to see the key's scopes. Ask a member who holds the scope to issue a key that includes it.
Retry: never
missing_capabilityHTTP 403
The Product or organisation has not enabled the feature this operation belongs to.
Enable it first (for example auth_enable or context_enable), then repeat the call.
Retry: after fixing
confirmation_requiredHTTP 409
The operation destroys or overwrites something and was sent without confirm: true.
The body carries the plan. Show it to the person responsible, then resend with confirm: true.
Retry: after fixing
budget_exceededHTTP 402
The key's spend cap would be passed by this operation.
Run the call with dry_run: true to see its cost, or use a key with a higher cap.
Retry: never
quota_exceededHTTP 402
A temporary account (from cloud_init) has used its quota.
Call cloud_claim to attach the account to a real organisation and lift the quota.
Retry: never
plan_limitHTTP 402
The organisation's plan does not include this many of the resource.
The body names the plan to move to in upgrade_to. Open billing, or remove something first.
Retry: never
not_foundHTTP 404
The id does not exist, or exists in another organisation.
List the parent resource to get a current id. Ids from another organisation are reported as missing.
Retry: never
conflictHTTP 409
The change clashes with the current state: a name in use, a build running, a step already done.
Read message for what holds the slot. Wait for it to finish, or choose another name.
Retry: after fixing
idempotency_mismatchHTTP 422
This idempotency_key was used before with a different body.
Use a new key for a new request. Reuse a key only to replay the identical call.
Retry: after fixing
rate_limitedHTTP 429
Too many requests from this key.
Wait for the retry-after header, then resend. Back off exponentially if it repeats.
Retry: later
internalHTTP 500
A fault inside Helm7. It has been reported automatically.
Retry once. If it repeats, quote request_id to support.
Retry: later