> ## 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.

# Errors and rate limits

> Status codes, error JSON, and which failures to retry.

Only a 2xx response spends credits. Any other response is stored in [List API Request Logs](/api-reference/usage/logs) with `credits_charged` of 0. Use the HTTP status, `error.code`, and `error.request_id` when you contact [support@defiorbit.xyz](mailto:support@defiorbit.xyz).

## Error body

Every failure uses this JSON:

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing API key.",
    "request_id": "req_..."
  }
}
```

## Status codes

| Status | Code | What to do |
| - | - | - |
| 400 | `MISSING_PARAMETER`, `INVALID_PARAMETER` | Fix the request. A missing `chain_id` where that route requires one is `MISSING_PARAMETER`. A bad address, page, or limit is `INVALID_PARAMETER`. |
| 401 | `INVALID_API_KEY` | Send `Authorization: Bearer` and a key shaped `do_sk_` plus 24 base62 characters. This code also covers a malformed header, an invalid key, and a revoked key. |
| 402 | `INSUFFICIENT_CREDITS` | Add credits, then call again. |
| 403 | `ACCOUNT_SUSPENDED`, `ENDPOINT_DISABLED`, `FEATURE_DISABLED` | Wait until access is restored. `FEATURE_DISABLED` means snapshots or MCP is turned off. |
| 404 | `NOT_FOUND`, `ORGANIZATION_NOT_FOUND` | The position or organization is not there. |
| 429 | `RATE_LIMIT_EXCEEDED` | Wait `Retry-After` seconds. The response also sets `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (unix seconds). |
| 500 | `INTERNAL_ERROR`, `API_ENDPOINT_NOT_CONFIGURED` | Unexpected failures use `INTERNAL_ERROR` and the message `An unexpected error occurred.` |
| 502 | `UPSTREAM_ERROR` | A transient upstream failure. Returned by portfolio balance, portfolio assets, the Orca position route, and Kamino routes. Retry after a short wait. |
| 503 | `SERVICE_UNAVAILABLE` | Uniswap V3 and Aerodrome V3 full position, when that position's data is not ready yet. Any route can also return this transiently, with `Retry-After: 1`. |
| 504 | `GATEWAY_TIMEOUT` | Kamino batch only. Retry with fewer wallets. |

Each reference page shows 200, then 400, 401, 402, 403, 429, and 500. 502, 503, and 504 are on the page for the route that returns them.

Any other failure is returned as `NOT_FOUND` on 404, `INVALID_REQUEST` on any other 4xx, and `INTERNAL_ERROR` on 5xx.

## Retry

Retry `429` after the `Retry-After` value. Retry `502`, `503`, and `504` after a short wait. Leave `400`, `401`, `402`, `403`, and `404` alone until the request or the account changes.

```javascript theme={null}
const retryable = new Set([429, 502, 503, 504]);

for (let attempt = 0; attempt < 4; attempt++) {
  const response = await fetch(url, {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  });
  const body = await response.json();

  if (response.ok) return body;

  if (!retryable.has(response.status)) {
    const { code, request_id } = body.error;
    throw new Error(`${response.status} ${code} (${request_id})`);
  }

  const retryAfter = Number(response.headers.get("Retry-After"));
  const waitMs =
    response.status === 429 && Number.isFinite(retryAfter)
      ? retryAfter * 1000
      : 500 * 2 ** attempt + Math.random() * 250;

  await new Promise((resolve) => setTimeout(resolve, waitMs));
}

throw new Error("DeFi Orbit API kept failing");
```

## Suspended organizations

Suspending an organization suspends its DeFi Orbit API access. Calls then return 403 `ACCOUNT_SUSPENDED`. Restoring the organization restores API access with the same keys and credit balance. While it is suspended, creating a key from the dashboard returns HTTP 403 with `ACCOUNT_SUSPENDED`. Contact [support@defiorbit.xyz](mailto:support@defiorbit.xyz) if you need the organization resumed.

## Rate limit

New organizations start at 5 requests per second. The limit applies to the organization, and it can be adjusted.

## Request logs

`GET /v1/usage/logs` returns method, path, status code, latency, credits charged, time, and the key id and name. Filter with `range` (`5m`, `1h`, `24h`, `7d`, `30d`), `from` and `to`, `api_key_id`, `path`, `status_code`, and `errors` (`all`, `success`, or `errors`).


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