> For AI agents: the documentation index is at https://platform.detectif.ai/llms.txt. Every page is also available as Markdown by adding `.md` to its path.

# Noesis errors

The error body of the REST endpoints, every error code, the WebSocket error event and its close codes.

## REST endpoints

Every error response from `https://api.noesis.detectif.ai` has the same JSON body as the rest of the DetectifAI API:

```json
{
  "error": {
    "type": "not_found",
    "code": "session_not_found",
    "message": "No session with this session_id exists in your account.",
    "param": "session_id"
  },
  "request_id": "req_8f14e45fceea167a5a36dedd"
}
```

- Use `error.code` in your code; it does not change. Show `error.message` to people; its wording can change.
- Include the `request_id` when you contact support.

### Error codes

| Status | Meaning | Code | How to fix |
|---|---|---|---|
| `400` | The request is invalid, for example an API key in the URL or an unsupported parameter. | `invalid_body` |  |
|  |  | `api_key_in_url` | Send the key only in the Authorization header (or use a stream token), then rotate the key that was in the URL. |
|  |  | `unsupported_parameter` | Remove the parameter: callback_url and webhooks are not offered on the platform; read results on the socket or the session. |
|  |  | `invalid_parameter` | Check the field named in error.param. |
| `401` | The API key is missing, invalid or revoked. | `invalid_api_key` | Check that the whole key was copied, or create a new one in the dashboard. |
|  |  | `missing_api_key` | Add the header Authorization: Bearer <your API key>, or a stream token for the WebSocket. |
|  |  | `invalid_stream_token` | Create a new stream token: each one opens one call and expires after 5 minutes. |
| `402` | Your balance is too low for this call or file. | `insufficient_credits` | Check your balance on the dashboard Overview page. |
| `403` | The key lacks the required scope, the e-mail address is not verified, or the account is suspended. | `insufficient_scope` | Use a key that is allowed to use Noesis, or create one in the dashboard. |
|  |  | `email_not_verified` | Verify your email address, then try again. |
| `404` | No session with this id exists in your account. | `session_not_found` | Check the session ID; only the account that created a session can read it. |
| `408` | The upload did not arrive in time. | `upload_timeout` |  |
| `409` | A request with the same Idempotency-Key is still running. | `operation_in_progress` |  |
| `413` | The file is larger than 50 MB. | `file_too_large` | Send a WAV file up to 50 MB and 15 minutes long. |
| `415` | Not a WAV file. | `unsupported_format` |  |
| `422` | The recording is too short or too long, or the Idempotency-Key was used for a different request. | `audio_too_long` |  |
| `429` | Too many requests, or too many calls and file analyses at the same time. Wait for Retry-After seconds. | `concurrency_limited` | Wait for a live call or recording to finish, then retry. |
|  |  | `rate_limited` | Wait for the Retry-After seconds, then retry. |
| `500` | Something went wrong on our side. | `internal_error` |  |
| `503` | Noesis is busy or temporarily unavailable. Retry after the Retry-After seconds. | `noesis_capacity` |  |
|  |  | `server_busy` | Busy, try again after the Retry-After seconds; carry on with the call without detection. |
## The WebSocket

On a live call, an error arrives as an event, and then the socket closes:

```json
{"type": "error", "code": "insufficient_credits", "error": "Your credit balance ran out.", "status": 402}
```

| Close code | Status | Meaning | What to do |
|---|---|---|---|
| `1003` | `400` | A parameter is invalid or not available; the message names it | Fix the URL |
| `4401` | `401` | The key or stream token is missing, invalid, expired or already used | Check the key, or create a new token |
| `4402` | `402` | The credit balance ran out | Add credits in the dashboard |
| `4403` | `403` | The key is not allowed to use Noesis, or the email address is not verified | Use a key with `noesis:detect` |
| `4429` | `429` | Too many calls at once, or new calls too fast | Wait for a call to end |
| `1013` | `503` | Busy | Carry on with the call without detection |
| `1000` | `408` | The socket was silent for 15 minutes, or the call passed 2 hours | Open one socket per call |

A frame or message that is too large gets an `error` event with status `413`, and the socket stays open.

## Never block a call

If the connection fails, is refused or closes early, carry on with the call as you would without Noesis. Retry `429` and `503` on the next call, not by holding the current one.