> For the complete documentation index, see [llms.txt](https://k-ai.gitbook.io/knowledge-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k-ai.gitbook.io/knowledge-ai/reference/errors.md).

# Errors & status codes

## HTTP status codes

| Code | Meaning               | When you'll see it                                                                          |
| ---- | --------------------- | ------------------------------------------------------------------------------------------- |
| 200  | OK                    | Successful request, payload in `response`.                                                  |
| 201  | Created               | Resource created.                                                                           |
| 400  | Bad Request           | Invalid request body or missing required field.                                             |
| 401  | Unauthorized          | Missing or invalid credentials.                                                             |
| 403  | Forbidden             | Credentials valid but not authorised for this resource (e.g. instance not visible to user). |
| 404  | Not Found             | Resource (instance, document, conflict) does not exist.                                     |
| 409  | Conflict              | State-machine violation (e.g. trying to close an already-managed conflict).                 |
| 422  | Unprocessable Entity  | Request body validates but is semantically wrong (e.g. answer length exceeds limit).        |
| 429  | Too Many Requests     | Rate limit hit (auth: 5 logins/min/IP).                                                     |
| 500  | Internal Server Error | Unexpected server failure. Exponential backoff retry recommended.                           |
| 502  | Bad Gateway           | Upstream component (LLM router, vector store) unreachable.                                  |
| 503  | Service Unavailable   | Service in maintenance or degraded; respect the `Retry-After` header.                       |

## Error body shape

All three APIs return `{"detail": "<message>"}` on error. The success wrapper `{"response": ...}` is only present on 2xx.

```json
{
  "detail": "Instance not found"
}
```

## Per-API specifics

### Instance API — `api.kai-studio.ai`

* `401` — wrong `instance-id` or `api-key` header.
* `404` — instance unknown to the platform.

### Retrieval API — `api-retrieval.kai-studio.ai`

* `401` — token expired or revoked.
* `403` — instance access denied (group RBAC).
* `422` — query length or pagination parameter violation.

### Audit API — `api-audit.kai-studio.ai`

* `409` — conflict already managed or ignored.
* `422` — workflow-state mismatch (e.g. answering a conflict that is in `MANAGED` state).

## OAuth-specific errors

OAuth 2.1 endpoints return standard error responses defined in [RFC 6749 §5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2):

| Error code               | Meaning                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| `invalid_request`        | Required parameter missing, included twice, or malformed.                                        |
| `invalid_client`         | Client authentication failed (unknown `client_id` or bad client secret).                         |
| `invalid_grant`          | Authorization code, refresh token, or resource-owner credential is invalid, expired, or revoked. |
| `unauthorized_client`    | Client is not authorised to use the requested grant type.                                        |
| `unsupported_grant_type` | The grant type is not supported by the authorisation server.                                     |
| `invalid_scope`          | Requested scope is invalid, unknown, malformed, or exceeds the granted scope.                    |

See the [OAuth 2.1](/knowledge-ai/authentication/oauth.md) page for the full authentication flow.