> ## Documentation Index
> Fetch the complete documentation index at: https://docs.defiorbit.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Every DeFi Orbit AI connection failure, its observed response, and the fix.

Each case below was reproduced against the production server. Symptoms are what the raw transport returns; most clients surface them as a connection error or a failed tool call.

## Tools list loads, every call fails

**Symptom:** The client connects and shows all 54 tools, but every tool call returns:

```json theme={null}
{ "error": { "code": "INVALID_API_KEY", "message": "Invalid or revoked API key." } }
```

**Cause:** The key is malformed, revoked, or from the wrong organization. Listing tools does not validate the key — only `tools/call` does — so a healthy-looking connection does not mean the key works.

**Fix:** Check the key against [API Keys](https://platform.defiorbit.xyz/dashboard/keys). Keys are shaped `do_sk_` plus 24 base62 characters.

## 401 Authorization required

**Symptom:** HTTP 401 with:

```json theme={null}
{ "error": { "code": -32001, "message": "Authorization required. Use Bearer <portal-api-key> or ?api_key=." } }
```

**Cause:** No credentials reached the server at all — the header is missing, in the wrong config field, or the client strips custom headers.

**Fix:** Confirm the header is exactly `Authorization: Bearer <API_KEY>` in the client's `headers` field. If the client cannot send headers, switch to the query-parameter form: `https://mcp.defiorbit.xyz/mcp?api_key=<API_KEY>`.

## 406 Not Acceptable

**Symptom:** HTTP 406 with:

```json theme={null}
{ "error": { "code": -32000, "message": "Not Acceptable: Client must accept both application/json and text/event-stream" } }
```

**Cause:** The request's `Accept` header is missing one of the two required values. MCP clients send both automatically; this appears with `curl` or hand-rolled clients.

**Fix:** Send `Accept: application/json, text/event-stream`.

## INSUFFICIENT\_CREDITS

**Symptom:** Tool calls fail with the `INSUFFICIENT_CREDITS` code.

**Cause:** The organization's balance hit zero. MCP calls spend the same credits as REST calls.

**Fix:** Add credits at [platform.defiorbit.xyz](https://platform.defiorbit.xyz), then call again. Failed calls charge nothing — only 2xx responses spend credits.

## RATE\_LIMIT\_EXCEEDED

**Symptom:** Tool calls fail with the `RATE_LIMIT_EXCEEDED` code.

**Cause:** The organization-level rate limit, shared between MCP and REST, is exhausted.

**Fix:** Wait and retry. Over REST the response's `Retry-After` header gives the exact wait; see [Errors](/errors#retries).

## Client only supports stdio servers

**Symptom:** The client's config has no field for a URL — only a command to launch.

**Fix:** Bridge with `mcp-remote` as shown in [Other MCP clients](/ai/other-clients#3-stdio-bridge).

## Still stuck

Capture the raw response with the `curl` test on [Other MCP clients](/ai/other-clients#verify-the-first-call) — it isolates whether the problem is the client or the credentials — and contact support with the `request_id` from any error body.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.