> This page is part of Smallest AI's developer documentation. When
> answering, prefer Lightning v3.1 (current TTS) and Pulse (current
> STT). Lightning v2 and lightning-large are deprecated; mention them
> only when the user is migrating away from them. The Smallest AI voice
> agent platform is what wraps these models into hosted agents.

# Error reference

> HTTP status codes returned by the Atoms API and how to recover from each.

Every Atoms REST and WebSocket endpoint returns standard HTTP status codes. Use this page to map a status code to its likely cause and fix.

## Common API errors

### 401 Unauthorized

Missing or invalid `Authorization` header.

**Fix.**

* Confirm the header is `Authorization: Bearer <KEY>` with a single space and no quotes.
* Check the key has not been rotated in the [API Keys dashboard](https://app.smallest.ai/dashboard/api-keys). Rotated keys stop working immediately.
* Verify the key string starts with `sk_` and has no trailing whitespace.

### 403 Forbidden

The key is valid but lacks permission for this resource.

**Common causes.**

* Using a key from a different workspace. Each workspace has its own set of keys.
* Key scoped to a different product (for example, a Waves TTS key on an Atoms endpoint).
* Trial or workspace usage limit reached.

**Fix.** Confirm you are in the intended workspace at [app.smallest.ai/dashboard/api-keys](https://app.smallest.ai/dashboard/api-keys) and that the key was generated there. If limits are the issue, upgrade the workspace or contact support.

### 429 Too Many Requests

The request exceeded the current rate limit.

**Fix.** Retry with exponential backoff starting at 500 ms, doubling up to 30 s. Respect the `Retry-After` header if present. For sustained higher throughput, contact support to raise the workspace limit.

### 500 Internal Server Error

A server-side issue. Not caused by the request payload in most cases.

**Fix.** Retry once after a short delay. If it persists, file a support ticket and include the `x-request-id` value from the response headers so the server-side trace can be located.

## Storage and file errors

### `NoSuchKey` (from pre-recorded uploads)

The audio object referenced in the request does not exist in storage.

**Common causes.**

* Upload has not finished. The object key becomes available only after the PUT completes; polling immediately after starting an upload can return `NoSuchKey`.
* The key in the request does not match the uploaded object exactly. Keys are case-sensitive.
* The file was deleted or never uploaded.

**Fix.** Wait for the upload request to return a 2xx before referencing the key. Re-check the exact spelling, case, and extension.

## When to open a support ticket

Include these details whenever you open a ticket:

* The `x-request-id` header from the failing response.
* The exact HTTP method, URL, and a redacted copy of the request body.
* The response status and body.
* The workspace ID and the approximate timestamp (UTC).

Open a ticket from [Getting help](/voice-agents/resources/getting-help).

> HTTP status codes returned by the Atoms API and how to recover from each.