Troubleshooting

The client cannot connect

Check the URLs against this documentation: the API is https://api.relvo.si and the MCP server https://app.relvo.si/mcp. Confirm that the credential is valid and that the client is using the supported authentication method.

If an authorization was revoked or expired, reconnect using the client’s authentication flow. npx --yes @relvo/cli doctor checks a CLI login and MCP registration without paid calls.

A tool is missing or access is denied

Check the selected project, the account’s membership and the key’s tool access. Reload the client’s tool list after changing credentials or permissions.

Availability can depend on the provider and the option selected in the app.

The request is rejected

Compare the submitted values with the current input schema. Check required fields, formats, provider options and the exact tool ID.

For a rate or quota limit, review the error and the relevant provider’s limits before retrying.

The result has not arrived

Use the execution ID to check whether the request is still working or has failed. A client timeout can happen while the underlying execution continues.

Preserve the tool ID, execution ID, time and error message when contacting support. Remove credentials and private input values from anything you share.

Read the error

Errors return an error object. status is the error class and message is a stable code for most errors: branch on it, not on wording. Some errors add details.

{
  "error": {
    "status": "PERMISSION_DENIED",
    "message": "platform_api_key_scope_required",
    "details": { "scope": "tools:execute" }
  }
}

Tool and connection access denials put a readable sentence in message and the code in details.code. A 500 returns Internal service error; a 503 names a platform_… code or returns Service unavailable. Retry both with backoff.

Common error codes

401 platform_bearer_credential_required
  Send Authorization: Bearer rlv_….

401 platform_developer_api_key_required
  Send a Relvo API key (rlv_…); this credential is not one.

401 platform_invalid_developer_api_key
  Create a new key; this one is unknown, revoked or expired.

400 platform_invalid_tool_request
  Fix the request body; for POST /tools/{tool}, its tool must match the path.

400 platform_invalid_tool_arguments
  Fix the paths in details.fields against the tool's input schema.

400 platform_idempotency_key_required
  Send an Idempotency-Key of 8–128 allowed characters.

400 platform_quote_changed
  Quote again and submit with the new priceVersion under a new key.

400 platform_connection_choice_required
  Choose one of details.connections and pass its id as connectionId.

400 platform_provider_own_key_required
  Add your own key for this provider in the app, or choose another provider.

403 platform_api_key_scope_required
  Use a key with the scope in details.scope.

403 platform_tool_access_denied
  Ask an admin for access to the tool in details.tool.

403 platform_approval_required
  An admin approves the call at details.reviewUrl, then retry.

404 platform_tool_unavailable
  The tool is not in your project's catalog.

409 platform_idempotency_key_used_for_another_request
  Use a new key for a different request.

400 platform_body_too_large
  The request body is over the endpoint's limit (413 above 16 MiB).

429 platform_insufficient_balance_or_spending_limit_reached
  Add balance or raise the limit named in details.reason.

429 platform_request_rate_exceeded
  Slow down and retry with backoff.

429 platform_api_key_suspended / platform_organization_suspended
  Too many rate-limited requests; wait for the suspension to end.

Rate limits and retries

1. 2,000 requests per minute per team, across all its keys, and per key. Reading the whole catalog with GET /tools counts as 200 requests, and a large response counts as one request per 256 KiB.
2. 30 requests refused by the rate limit within 10 minutes suspend the key or team for 15 minutes, then 1 hour, then 24 hours; meanwhile requests fail with 429 platform_api_key_suspended or platform_organization_suspended. A key suspended 3 times within 7 days is revoked.
3. 30 rejected credentials from one IP address within 5 minutes block that address; three blocks within 24 hours ban it for 24 hours.
4. 429 responses have no Retry-After header. Retry platform_request_rate_exceeded and 5xx with exponential backoff and jitter, starting at about one second. Other 429 codes, such as balance, spending-limit, upload and download limits, need their cause fixed first.
5. Retry a lost submission with the same Idempotency-Key and the same body. Do not resend 400, 401, 403 or 404 requests unchanged.

Size limits

64 KiB
  Request body

1 MiB
  Quote, execution, discovery and custom tool requests

16 MiB
  Upload and team skill requests

12 MiB
  Uploaded file

1 GiB
  Uploads per team in 24 hours

1 MiB
  Output of one provider request

14 MiB
  Response of a custom API endpoint with raised limits (1 MiB by default)

64 MiB
  Generated artifact

120 s
  Time to send a request

300 s
  One call of a custom API endpoint with raised limits (5 s by default)