Errors
Every status Operate As can answer with, what it means, and which ones are worth retrying.
When Operate As can't make the call, you get an HTTP error with a plain-words detail:
HTTP/1.1 409 Conflict
Content-Type: application/json
{ "detail": "Miller Dental's Google access ended. Send them their link to reconnect." }| Status | Means | What to do |
|---|---|---|
400 | A required input is missing, or the pass-through path tries to leave the service's API | Fix the request. detail names what's missing |
401 | No key, a key not starting oa_, or one that doesn't exist or was revoked | Check the Authorization header |
402 | The workspace has no plan | Choose a plan in the dashboard |
403 | Outside the key's clients, services or actions; the client wasn't asked to connect that service; the client paused the connection or allows only reads; your plan doesn't include it; the key is beyond your plan's key allowance; or your agency is suspended | detail says which. Widen the key's limits, add the service to the client, ask the client, revoke a key or upgrade |
404 | No such action, service or client | Check the name or ID |
409 | The client hasn't connected the service yet, or their access ended | Send the client their link. Retrying won't help |
422 | The body isn't valid, such as a missing clientId. detail is a list | Fix the request |
429 | Your plan allows no more API calls this period: the allowance on the free plan or with extra calls off, or on a paid plan, your monthly limit on extra calls or three times the allowance. Retry-After gives the seconds until they reset | Wait, or upgrade |
502 | The service didn't answer | Retry after a short wait |
503 | The provider couldn't renew the client's access right now | Retry after a short wait |
A 422 lists each problem:
{ "detail": [{ "loc": ["body", "clientId"], "msg": "Field required", "type": "missing" }] }The libraries turn each status into its own error class: Python, Node, Go.
Retries
| What to do | Statuses | Why |
|---|---|---|
| Retry with backoff | 502, 503 | Short outages at the service or provider. Wait 2, 4, then 8 seconds |
| Wait | 429 | No more calls this period. Retry-After says how many seconds, which can be days |
| Fix the call | 400, 401, 402, 403, 404, 422 | The same request fails the same way. Change it first |
| Needs a person | 409 | The client has to reconnect from their link. Retrying won't help |
For 429, read Retry-After before sleeping: it can be days, so pausing the workflow or alerting someone is usually better. For 409, listen for the connection.expired webhook to hear about it before a workflow runs into it. A service's own errors inside status, such as its own 429, follow that service's rules.