# Troubleshoot Aroai tool calls

Diagnose connection, authentication, access, quota and upstream errors without retrying blindly.

Canonical: https://aroai.com/docs/errors/

## Start with the returned error

Tool errors contain a stable code, a safe message and a retryable flag. Use those details to decide whether to correct the request, refresh access or wait for a dependency.

## Common checks

- [Authentication required](https://aroai.com/docs/authentication): Complete OAuth sign-in or check the bearer key, expiry and scope.
- [No permitted tools](https://aroai.com/integrations): Check endpoint, workspace membership, server status and client capability.
- [Credits exhausted](https://aroai.com/docs/credits): Review the billing period, remaining workspace credits and plan limit.
- [No search matches](https://aroai.com/recipes/nz-company-research): Try the registered name or a clearer spelling. No match is a valid result.

## Use retries with care

- Only retry a failure marked retryable, and respect upstream backoff guidance.
- Do not retry invalid input unchanged; check required fields, ranges and formats in the schema.
- Refresh a client's tool list after a catalog change. Some hosts keep an approved snapshot.
- If a failure persists, record the tool name, safe error code, approximate time and client version. Do not include API secrets or private source data in a support request.

## Partial results remain partial

A successful transport response does not make a source record complete. Review the returned fields, source limits, missing data and any execution follow-up needed.