Errors

Errors use RFC 9457 application/problem+json. Match on code, not on the message.

JSON

{
  "type": "https://setuagent.com/errors/invalid_input",
  "title": "INVALID_INPUT",
  "status": 400,
  "code": "INVALID_INPUT",
  "detail": "input.title is required",
  "retryable": false
}

Every response carries an X-Request-Id header. Include it when you report a problem.

Code	HTTP	Retry?	Meaning and fix
`INVALID_INPUT`	400	No	The request or the action input failed validation, or the user has several accounts for the toolkit and you must pass `connection_id`.
`UNAUTHORIZED`	401	No	The API key is missing, wrong or revoked.
`PERMISSION_DENIED`	403	No	The provider refused (the account or granted scopes do not allow it; reconnect with more scopes), or a destructive action was sent without `confirm: true`.
`ACTION_DISABLED`	403	No	The action is switched off for this project or session.
`NOT_FOUND`	404	No	Unknown action, or no connection for this user and toolkit. Send the user through connect.
`CONNECTION_NEEDS_REAUTH`	409	No	The provider rejected the stored token and it cannot be refreshed. Start a new connection.
`RATE_LIMITED`	429	Yes	Too many requests, from Setu's per-key limit or the provider's. Honor `Retry-After`.
`QUOTA_EXCEEDED`	429	No	The project's monthly call quota is used up.
`PROVIDER_ERROR`	502	Yes	The provider returned an error or an unusable response.
`TIMEOUT`	504	Yes	The provider did not answer in time.

Retries#

The SDKs retry 429 for every request and retry 5xx and network errors only for GET and DELETE. Setu never retries a write on a server error: a repeated "create issue" could create two issues. Reads inside an action retry on 5xx up to three times with backoff.

Destructive actions#

An action with risk: destructive returns PERMISSION_DENIED with a message asking for confirm: true until the caller sets it. Models should surface that to a person before confirming.