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

# Errors

> Every error the API returns, and what to do about it.

Errors come back as JSON, with a stable `error` code to test in your code. Some carry extra fields that help you react:

```json theme={"system"}
{
  "error": "invalid_request",
  "fields": [
    { "path": "q", "message": "Too small: expected string to have >=1 characters" }
  ]
}
```

Match on `error`, not on the wording of a `message`: messages can change, codes do not.

> [!NOTE]
>
> **A refused call never takes a search from your quota.** The input, your plan and the removals are checked before anything is counted, and a search refused by a limit is not counted either. The one exception is a `404` from a single-module route: it is an answer (“nothing there”), and it counts. [What takes a search →](https://docs.dis.dog/limits.md#what-takes-a-search)

## Error codes

### Your request

| Status | Code | What happened | What to do |
| - | - | - | - |
| `400` | `invalid_request` | `q` is missing, empty or longer than 100 characters. `fields` lists each problem. | Send `q` with 1 to 100 characters. |
| `400` | `invalid_query` | `q` is not a Discord ID, a username or an invite link DisDog can recognise. | Check the input — see [what you can search](https://docs.dis.dog/api-reference/endpoints/search.md#accepted-inputs). |
| `400` | `invalid_id` | The `{id}` in the path is not a valid Discord ID. | Send the 17 to 20 digit ID. |
| `400` | `invalid_name` | The `{name}` is shorter than 2 or longer than 64 characters. | Send 2 to 64 characters. |
| `400` | `invalid_invite` | The `{code}` is not an invite code or invite link. | Send the code (`disdog`) or the link (`discord.gg/disdog`). |
| `404` | `user_not_found` | `/v1/profile/{id}`: no Discord account has this ID. | Check the ID. This counts as a search. |
| `404` | `not_available` | `/v1/connections/{id}`: the connections could not be read for this account right now. | Try again later. This counts as a search. |
| `404` | `invite_not_found` | `/v1/invite/{code}`: the invite does not exist or has expired. | Nothing. This counts as a search. |
| `404` | `not_found` | No such route. | Check the path and the method: every route is `GET`. |
| `451` | `removed_by_owner` | The owner of this Discord ID asked to be removed from DisDog. | Nothing: the ID is hidden from every search, for everyone. See [Data removal](https://docs.dis.dog/data-removal.md). |

### Your key

| Status | Code | What happened | What to do |
| - | - | - | - |
| `401` | `invalid_api_key` | No key sent, or a key that matches no account — mistyped, or replaced by a newer one. | Send your current key in `Authorization: Bearer …`, or [get a new one](https://dis.dog/recover). |
| `403` | `plan_has_no_api` | A Pup (free) key, on a route other than `/v1/me` and `/v1/modules`. | [Upgrade to Hound or Alpha](https://dis.dog/pricing). |
| `429` | `too_many_requests` | More than 30 calls with a wrong key from your address in 15 minutes. | Fix the key, then wait up to 15 minutes. |

### Limits

| Status | Code | Extra fields | What happened | What to do |
| - | - | - | - | - |
| `429` | `rate_limited` | `retryAfterMs`, `resetAt`, `limit` | Pup (website): less than 3 seconds since your last search. | Wait `retryAfterMs` milliseconds. |
| `429` | `quota_exceeded` | `resetAt`, `limit` | Today’s searches are used up. | Wait for `resetAt` (00:00 UTC), or [upgrade](https://dis.dog/pricing). |

### Our side

| Status | Code | What happened | What to do |
| - | - | - | - |
| `500` | `internal_error` | Something broke on our side. | Try again; if it persists, [contact support](https://dis.dog/contact). |
| `502` | `source_unavailable`, `upstream_unavailable` | A data source did not answer. | Retry with a backoff (2 s, 5 s, 15 s). |
| `503` | `module_unavailable`, `upstream_busy` | A source is down or overloaded. | Retry later. |

In a [search](https://docs.dis.dog/api-reference/endpoints/search.md), a failing source never fails the whole call: that module answers `"status": "error"` and the others still come back.


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