Errors
Every API and SDK error code, and every tool refusal code, with the fix.
An API request error comes back as an HTTP error (an SdkError in the SDK). A session tool refusal
comes back to the model as { ok: false, error }. The request can succeed at the HTTP level without
the action succeeding. The model reads the refusal to decide what to do next.
Error codes
REST answers { "error": { "code", "message" } } with the status below. The SDK returns the same
code and message as an SdkError in a failed Result.
| Code | Status | Meaning | What to do |
|---|---|---|---|
VALIDATION_ERROR | 400 | Invalid body, query, or tool input. In the SDK, also a missing userId. | Read issues, fix the request. Set userId on the call or on new Dexby(). |
MISSING_CONNECTION | 400 | The user has not connected this connector. | Send the user a connect link. |
REAUTH_REQUIRED | 400 | The provider rejected the stored credential. | Send the user a connect link to connect again. |
CONNECTION_NOT_FOUND | 400/404 | The named account is not one of the user's for this connector. | List accounts with GET /v1/connections?userId=user_123 and pass a valid id. |
EXECUTION_ERROR | 400/500 | The tool failed at the provider or a credential rotation failed. In the SDK, also a network failure or unreadable response. | Read message. Retry only if the tool is safe to repeat. |
UNAUTHORIZED | 401 | API key missing, unknown, revoked, or expired. | Send Authorization: Bearer $DEXBY_API_KEY with a key from Configure → API keys in the dashboard. |
INSUFFICIENT_SCOPES | 403 | The account was granted neither a permission the tool needs nor a broader one that covers it. missingScopes lists them. | Send the user a connect link to connect again and approve them. Check the auth config's scopes include them. |
ACTION_DISABLED | 403 | The tool is turned off in the project or the account's auth config, or the chosen account is a global account whose admin has not allowed the tool (or proxying, for /v1/tools/proxy). | Turn it on in Build → Catalog or Build → Auth configs, or allow it in the global account's permissions under Connections. |
NOT_FOUND | 404 | No such route or resource. | Check the path and id. |
TOOL_NOT_FOUND | 404 | No such tool, or the session has no tool with that name. | Get ids from GET /v1/tools or names from GET /v1/sessions/:id/tools. |
CONNECTOR_NOT_FOUND | 404 | No such connector. | Get ids from GET /v1/connectors. |
SESSION_NOT_FOUND | 404 | No such session, or it expired. | Create a new session. |
AMBIGUOUS_CONNECTION | 409 | The user has several active accounts, global ones included, and no default; or a name matches both their own and a global account. | Pass connectionId (one of choices, where global: true marks a global account), or set a default with POST /v1/connections/:id/default. |
CONFLICT | 409 | The resource already exists, or expectedRevision is stale. | Pick another name, or reread the connection and retry with the current revision. |
CONNECTOR_UNAVAILABLE | 409 | The connector behind an auth config is no longer available. | Pick another auth config in Build → Auth configs. |
INTERNAL_ERROR | 500 | Unexpected server error. The message has no details. | Retry. If it persists, check Operate → Logs. |
UPSTREAM_ERROR | 502 | The provider, an MCP server, or an imported API failed or could not be reached. | Retry later. Check the provider's status and limits. |
CREDENTIAL_UNAVAILABLE | 503 | A stored secret could not be read or written. | Retry later. If an account was being added, refresh the list before retrying. |
CANCELLED | SDK | The AbortSignal fired. | Nothing, unless the abort was unexpected. |
UNKNOWN | SDK | A code this SDK version does not know. | Read message. |
REST-only codes (the SDK reports them as UNKNOWN):
| Code | Status | Meaning | What to do |
|---|---|---|---|
FORBIDDEN_ENDPOINT | 403 | POST /v1/tools/proxy refuses this connector or path. | Use a connector with a proxy base URL and a path on its host. |
NAME_TAKEN | 409 | The user already has an account with that name for this connector. | Choose another name. |
Codes of the hosted Connect page (FORBIDDEN, LINK_USED, LINK_EXPIRED) are in
public endpoints. GET or DELETE on an MCP route answers 405 with no body.
Refusal codes
A session tool answers { ok: false, error: { code, message } } with HTTP 200. message tells
the model what to do next; some refusals add fields such as connector, choices, or issues.
| Code | Meaning | Fix |
|---|---|---|
validation_error | The arguments do not match the tool's schema. Includes issues. | The model reads the schema with dexby_get_action_schemas and calls again. |
action_not_allowed | The tool is not in the session's scope, or does not exist. | Find tools with dexby_search_actions, or widen connectors, actions, or policy. |
connector_not_allowed | The connector is not in the session's scope. | Add it to the session's connectors. |
connection_required | The user has not connected the connector. Includes connector. | The model calls dexby_connect_account and gives the user the link. |
reauth_required | The stored credential was rejected. Includes connector. | Same: the user connects again through the link. |
account_selection_required | Several accounts and no default. Includes choices and accounts (id, name, global). | The model retries with account, or asks the user. Or set accounts on the session. |
account_not_found | The named account does not exist for this user and connector. | The model calls dexby_list_connections and uses a listed account. |
not_permitted | dexby_proxy sent a non-GET request in a read-only session, the agent tried to make a global account the default or disconnect it, or a global account is not permitted to run the action or proxy. | Use GET, or create the session without policy.readOnly. For a global account, ask an admin to allow the action. |
path_not_allowed | dexby_proxy refused the path. | Use a path on the connector's API host. |
path_not_found | dexby_read_result found nothing at path. | Read the result from its root, then pick a valid path. |
result_not_found | The stored result expired or belongs to another session. | Run the tool again. |
connect_unavailable | A connect link could not be made. | Check the connector's auth config in Build → Auth configs. |
idempotency_conflict | The idempotencyKey was already used for a different request. | Use a new key. |
in_progress | The first call with this idempotencyKey is still running. | Retry shortly with the same key. |
upstream_error | The provider or the tool failed. | Read message. Retry only if the tool is safe to repeat. |
An idempotencyKey (1 to 200 characters) on dexby_execute makes a retry within 24 hours return
the first outcome with replayed: true. When nothing ran (validation_error,
action_not_allowed, account_not_found, connection_required, reauth_required), the key is
released. See sessions.