# Errors

> Every error of the Moknah REST API, the WebSocket streams, the Article to Speech API and the MCP tools, with its cause and the fix.

## Error formats

REST errors raised by endpoint logic:

```json
{"success": false, "error": {"code": "ERROR_CODE", "message": "What went wrong", "details": {}}}
```

`details` appears only when there is more to say. Three framework-level errors are flat instead: `authentication_failed` (401), the 403 for a key without access to a service, and `method_not_allowed` (405).

WebSocket errors are either a JSON text frame `{"error": "message"}` or a close code.

Article to Speech errors are `{"code": "ERROR_CODE", "error": "message"}`.

MCP tool errors are `{"ok": false, "error": {"code": "ERROR_CODE", "message": "...", "details": {}}}`.

## REST API errors

### `INVALID_REQUEST` (HTTP 400)

A field is missing, has the wrong type or an unsupported value. `error.details` maps each field to its problem.

Common causes: missing `text` or `voice_id`; text longer than 1,500 characters; a `voice_id` that does not exist, is not available to the account, or belongs to the other voice type than the key; an unknown key inside `voice_settings`; an invalid `mode`, `style`, `pace` or `output_format`; `prerecording` 2 or 3 with a language other than Arabic; an unknown `language` code; for the voice list, an `engine` that is not the key's voice type.

Fix the request. Retrying it unchanged gives the same error.

### `INVALID_AUDIO` (HTTP 400)

The file sent to `POST /api/v1/stt/submit/` could not be read as audio. Send a standard audio file such as MP3, WAV or M4A.

### `authentication_failed` (HTTP 401)

```json
{"error": "authentication_failed", "message": "Authentication required. Provide a valid API key or the ip address isn not allowed."}
```

Causes: no `Authorization: Bearer` header; a key that does not exist; a key that is revoked, inactive, expired or over its own credit limit; a deactivated account; a request from an address outside the key's IP allowlist.

Check the key in the dashboard under **API**, **Manage API Keys**. The body does not say which cause applies.

### `INSUFFICIENT_CREDITS` (HTTP 402)

The account balance does not cover the request. For text to speech, `error.details` has `credits_remaining` and `credits_used` (the credits the request needs), and the response has the headers `Moknah-Credits-Remaining` and `Moknah-Credits-Used`.

Buy credits or move to a larger plan, then retry. See [Pricing](../pricing/index.md).

### `CREDIT_LIMIT_EXCEEDED` (HTTP 402)

The API key has its own total credit limit and this request would pass it. The account may still have credits. Raise the key's credit limit, or use another key.

### Forbidden: no service access (HTTP 403)

```json
{"detail": "API key does not have access to this service."}
```

The key's allowed services do not include the one called (`tts`, `tts_ws`, `stt`, `stt_ws`). Edit the key and allow the service.

### `JOB_NOT_FOUND` (HTTP 404)

`GET /api/v1/stt/status/{job_id}/` was called with an id that does not exist or belongs to another key. Use the `job_id` returned by the submit call, with the same key.

### `method_not_allowed` (HTTP 405)

The endpoint was called with the wrong HTTP method. `POST /api/v1/voices/` and `POST /api/v1/tts/generate/` are POST; the job status and key endpoints are GET.

### `CONTENT_REJECTED` (HTTP 422)

The text was refused by the automatic content policy check. Do not retry the same text. The content policy is at https://moknah.io/content-policy/.

### `CONCURRENT_REQUEST` (HTTP 429)

Another text to speech REST request of the same account is still running. Requests run one at a time per account. Wait for the first response, then send the next request. Queue requests on your side.

### `RATE_LIMIT_EXCEEDED` (HTTP 429)

The requests per minute or credits per minute limit was reached. The response has `Retry-After` (seconds) and `RateLimit-Reset`, and `error.details` has `reset_after`. Wait, then retry. Current limits are in [Limits](../limits/index.md); sales@moknah.io can raise them.

### `JOB_FAILED` (HTTP 500)

A speech to text job failed while processing. The credits taken for it are refunded automatically. Submit the file again; if it fails again, check that the file is valid audio.

### `INTERNAL_SERVER_ERROR` (HTTP 500)

Something failed on Moknah's side. For text to speech, `error.details.request_id` identifies the request. Retry with backoff. If it persists, send the `request_id` to support@moknah.io. When the request was charged, a refund request is created automatically.

### Generation error codes (HTTP 500)

Text to speech can also answer `500` with the code `tts_generation_error` or `audio_processing_error` when the voice engine failed. Treat them like `INTERNAL_SERVER_ERROR`: retry with backoff.

## WebSocket close codes

### Close code 1000

Normal end of a stream.

### Close code 3011

Text to speech stream only. Audio generation failed. An `{"error": "Audio generation failed. Please try again."}` frame is sent first. Open a new stream and send the text again.

### Close code 4001

No API key was sent. Add `Authorization: Bearer YOUR_API_KEY` to the handshake, or `?api_key=` in the URL.

### Close code 4002

Authentication failed, or credits are insufficient. An error frame sent just before the close says which: invalid or inactive key, a key without `tts_ws` or `stt_ws` access, an IP address that is not allowed, no credits to start, or for speech to text no credits to continue.

### Close code 4009

Speech to text stream only. An audio frame was larger than 256,000 bytes. Send frames of about 100 ms.

### Close code 4290

The account already has an open stream of this service. One stream per account and service is allowed. Close the other stream; after a crash, wait about 15 seconds for the lock to clear.

### Stream error messages

Errors that arrive as `{"error": "..."}` frames, such as `Chunk too large. Maximum 2000 characters per chunk.`, `Not initialized. Send init message first.` and `Insufficient credits during stream`, are listed with their causes in [Stream speech](../api/tts-stream.md#messages-you-receive) and [Stream transcription](../api/stt-stream.md#close-codes).

## Article to Speech errors

### `AUTH_FAILED` (HTTP 401)

The `Authorization` header is missing, the company API key is invalid, or the key's company does not have the Article to Speech service. This endpoint needs the company key, not a dashboard API key.

### `VALIDATION_ERROR` (HTTP 422)

`text` is missing or blank, a `postData` field is missing or invalid, the text is too short to narrate, or `preprocessType` 2 was sent with a language other than Arabic. The `error` text names the field.

### `INVALID_VOICE_ID` (HTTP 400)

`voiceId` does not exist. Take the id from the voice list.

### `UNSUPPORTED_VOICE` (HTTP 400)

The voice is not of the company key's voice type (Standard or Advanced), or it is not available right now. Choose a voice whose `voice_engine` equals the key's type.

### `ALREADY_PROCESSING` (HTTP 409)

This `articleId` is being generated right now. Wait for the callback instead of sending it again.

### `PROCESSING_ERROR` (HTTP 422)

Generation could not start or failed. Credits taken are refunded. Send the article again later.

### `REFUND_FAILED` (HTTP 422)

Processing failed and the automatic refund did not complete. Contact api@moknah.io with the `articleId`.

### Too many requests to Article to Speech (HTTP 429)

More requests came from one IP address than the limit allows. The body is plain text. Space out the requests; see [Limits](../limits/index.md).

## MCP tool errors

### `UNAUTHENTICATED`

The MCP token is missing, invalid, revoked or expired. Connect again.

### `FORBIDDEN`

The signed-in user may not act on this item, or the chosen voice is not in their plan. An assistant can only reach the user's own and team content.

### `NOT_FOUND`

The project, chapter, line, voice, job or document does not exist or is not visible to the user. For documentation tools, `error.details.suggestions` lists valid values.

### `INVALID_INPUT`

An argument failed validation, for example a chapter with more lines than allowed, a line that is too long, or a destructive tool called without its confirmation argument. The message says what to change.

### `INSUFFICIENT_CREDITS` (MCP)

The balance does not cover the work. `error.details` has `required`, `balance`, `shortfall`, `buy_credits_url` and `subscribe_url`. Give the user both links and offer to continue after they top up.

### `UPGRADE_REQUIRED`

The tool belongs to Audio Studio and the user's plan does not include it. `error.details.subscribe_url` is the plans page. `text_to_speech` still works on every plan.

### `SCOPE_DENIED`

The token is limited to some groups of tools and this tool is not among them.

### `CONFIRMATION_REQUIRED`

The action needs the user's explicit agreement, for example creating a very large project. Ask the user, and call again with the confirmation argument only on a clear yes.

### `RATE_LIMITED`

Too many calls in a short time. Wait and retry.

### `NOT_IMPLEMENTED`

The capability is not available through MCP.

### `INTERNAL`

An unexpected failure. `error.details.request_id` identifies the call. Retry once; if it fails again, give the user the `request_id` for support@moknah.io.

## How to handle errors in code

| Status | Retry? | Action |
| --- | --- | --- |
| 400, 422 | No | Fix the request. |
| 401, 403 | No | Fix the key or its permissions. |
| 402 | No | Add credits or raise the key's credit limit. |
| 404, 405 | No | Fix the URL, the id or the method. |
| 409 (Article to Speech) | Later | Wait for the callback. |
| 429 | Yes | Wait `Retry-After`, or back off: 1, 2, 4, 8 seconds. |
| 500 | Yes | Back off; report the `request_id` if it persists. |
