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

# Error Codes and Responses

> Every VyomFlow API error returns a uniform JSON envelope. This page lists all status codes, error codes, and what to do when you see them.

Every error in the VyomFlow API uses the same JSON envelope, so you can write one handler for all failure paths. The envelope contains an error code you can switch on, a human-readable message, and — for some error codes only — a `details` field with structured validation metadata.

## Error envelope

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found."
  }
}
```

<Note>
  `details` is omitted entirely when there is nothing to report — it is never sent as `null`. Only `BAD_REQUEST` and `CONFLICT` populate it (for example, with Zod's flattened validation errors); every other error code omits the key.
</Note>

## Status codes and error codes

| HTTP Status | Code                   | Meaning                                                                     | What to do                                                                                       |
| ----------- | ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| 400         | `BAD_REQUEST`          | Request body or query failed validation                                     | Check your request body against the schema                                                       |
| 401         | `UNAUTHORIZED`         | Missing, invalid, expired, or revoked credential                            | Session callers: refresh your Clerk token. API-key callers: check the key is valid and unrevoked |
| 402         | `INSUFFICIENT_CREDITS` | Not enough credit balance                                                   | Check your balance; reduce message complexity                                                    |
| 403         | `FORBIDDEN`            | Valid API key, but missing a required scope                                 | Add the missing scope to the key (see [Authentication](/authentication))                         |
| 404         | `NOT_FOUND`            | Resource does not exist or belongs to another user                          | Verify the resource id and that you own it                                                       |
| 409         | `CONFLICT`             | Request conflicts with current state (for example, a run is already active) | Wait for the active run to complete before sending another message                               |
| 429         | `RATE_LIMITED`         | Per-user send-rate limit exceeded                                           | Retry after a short wait                                                                         |
| 503         | `REALTIME_UNAVAILABLE` | Turn dispatched successfully but realtime token minting failed              | The message was accepted; retry fetching the realtime token                                      |
| 500         | `SERVER_ERROR`         | Unexpected server-side failure                                              | Retry with exponential backoff; contact support if persistent                                    |

<Note>
  404 is deliberately non-leaking: a chat that was never yours and a chat that never existed produce byte-identical responses.
</Note>