Retry, or don't

Most failures against this gateway are permanent, and retrying them wastes the user's allowance to arrive at the same answer. A few are transient and worth one more attempt. The message tells you which.

The rule

Retry only when the failure is about timing. Never retry when it is about correctness or permission.

What came back	Retry?	Do this instead
400, invalid parameter	No	Fix the named field. Re-read the schema.
401, invalid key	No	The credential is wrong or revoked. Say so.
404, missing resource	No	Wrong slug or wrong account.
409 on a credentialed server	No	Connect or disconnect it in the app.
429, rate limit	Yes	Wait exactly the Retry-After seconds.
500	Yes	Bounded exponential backoff, a few attempts, then stop.
Policy denial	No	The account switched this off deliberately.
Approval pending	No — wait	See handling-held-and-refused-calls.

Rate limit is not quota

Two different limits, two different answers, and confusing them sends the user to a pricing page for a problem that resolves in thirty seconds.

Rate limit is per minute. The message says so, gives a number of seconds, and states that nothing was consumed. Wait that long and call again. Do not tell the user to upgrade.

Quota is the monthly allowance. On the free plan calls are refused once it is spent, until the counter resets. That one genuinely is a plan question.

Read which one you got before advising anything.

Backoff, briefly

For a 500 or a transport failure: one retry after roughly a second, a second after roughly four, then stop and report it. Do not retry indefinitely, and do not retry a run_tool that may have already acted — a write that returns a 500 may still have happened. Check before repeating it.

Relay the message

Omniio's error text is written to be read by whoever has to fix it: it names the limit, says whether anything was consumed, and gives the exact wait. Passing it through is more useful than summarising it as "the request failed".