Handle errors
Read the code, check whether anything was charged, then retry only when it is safe.
Error shape
- ScreenRequest
- ActionError code
- ResultMessage with the fix
Send without fundsNothing is charged; top up to continue
Example dataOpenAI routes answer { error: { type, code, message } }. The Anthropic route answers { type: "error", error: { type, message } } with the code in type. REST answers { error: { code, message } }.
{
"error": {
"type": "invalid_request_error",
"code": "insufficient_funds",
"message": "your balance does not cover this call. top up in console."
}
}Was I charged?
- ScreenError
- ActionHold released
- ResultNothing charged
Call a paused endpointRefused before any charge
Example dataNo gateway error charges you: holds are released. The only charged cases are streams that already produced output and then stopped (client_closed, stream_interrupted); you pay for what was generated.
Retry rules
- ScreenCode
- ActionFix or wait
- ResultRetry
Send without fundsNothing is charged; top up to continue
Example dataGateway calls are never replayed from storage. A timeout on your side is not proof of failure: look for the receipt before you send the call again.
| Code | Retry? | Do this |
|---|---|---|
insufficient_funds (402) | After funding | Top up or change funding |
key_limit_reached, model_not_allowed, key_disabled (403) | After changing the key | Edit the key in Console |
rate_limited (429) | Yes, with backoff | No retry-after on the gateway; back off yourself |
endpoint_paused (503) | Later | Pick another endpoint or wait for resume |
upstream_unavailable (503) | Yes | Retry or pick another model |
allowance_closing (409) | In a few minutes | Or use balance funding |
Safe retries on account writes
- ScreenWrite
- ActionIdempotency-Key
- ResultSame answer once
Name it, set limits, createThe secret is shown once
Example dataSigned-in REST writes accept Idempotency-Key (8 to 128 of letters, digits, _ or -). A retry with the same key and body gets the first answer with idempotent-replayed: true; a different body gets 422 idempotency_mismatch. A replayed key creation returns key: null: the secret is shown once only.