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

# Errors

> Error codes and response shapes returned by the API

All errors return a JSON body with the same shape:

```json theme={null}
{
  "error_code": "not_found",
  "message": "Connection 'conn_123' not found.",
  "details": { ... }
}
```

`details` is optional and present when there is structured context (e.g. missing scopes, validation fields).

## Error codes

| HTTP | `error_code`                   | Description                                                              |
| ---- | ------------------------------ | ------------------------------------------------------------------------ |
| 400  | `bad_request`                  | Invalid request.                                                         |
| 400  | `provider_not_supported`       | The requested provider is not supported.                                 |
| 400  | `oauth_state_invalid`          | OAuth state parameter is missing or invalid.                             |
| 401  | `authentication_error`         | Invalid or missing credentials.                                          |
| 403  | `permission_denied`            | Authenticated but lacks the required permission.                         |
| 403  | `insufficient_scopes`          | API key is missing required scopes. `details.missing_scopes` lists them. |
| 404  | `not_found`                    | Resource not found.                                                      |
| 404  | `connection_not_found`         | Connection not found.                                                    |
| 404  | `client_not_found`             | Client not found.                                                        |
| 409  | `conflict`                     | Request conflicts with existing state.                                   |
| 422  | `unprocessable_entity`         | Request body failed validation.                                          |
| 429  | `rate_limit_exceeded`          | Rate limit exceeded.                                                     |
| 500  | `internal_server_error`        | Unexpected server error.                                                 |
| 502  | `upstream_error`               | A downstream dependency returned an error.                               |
| 502  | `oauth_provider_error`         | OAuth provider returned an error.                                        |
| 502  | `knowledge_engine_error`       | Knowledge engine returned an error.                                      |
| 503  | `knowledge_engine_unavailable` | Knowledge engine is not available.                                       |