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

# Troubleshooting: ATTACHMENT_TOO_LARGE and AUDIO_TOO_LARGE

> Resolve the 422/413 size-cap rejections ATTACHMENT_TOO_LARGE and AUDIO_TOO_LARGE on ticket attachments and audio uploads — tell a deterministic size cap from a storage fault, find the per-surface limit, and shrink, re-encode, or split the file instead of retrying.

# Troubleshooting: ATTACHMENT\_TOO\_LARGE and AUDIO\_TOO\_LARGE

These two codes are **deterministic size caps**: the API rejected the
payload before any upload happened, so nothing was stored and nothing
will change on retry. `ATTACHMENT_TOO_LARGE` fires on Inbox ticket
attachments past the 25 MiB per-attachment ceiling. `AUDIO_TOO_LARGE`
fires on an audio clip past the surface's limit — most commonly a
voice-upload endpoint that accepts up to 2 MB, or the voice-biometrics
enrollment sample capped at 30 seconds / 2 MB. Both are fixable on the
sender side: reduce the bytes and retry once.

```json theme={null}
{
  "error": {
    "code": "ATTACHMENT_TOO_LARGE",
    "message": "Attachment exceeds the 26214400-byte limit",
    "status": 422
  }
}
```

## 1. Which cap is which

Match the surface you were calling to the cap it enforces:

| Surface                                                                        | Code                         | Limit                                                                 | Fixable by                                                  |
| ------------------------------------------------------------------------------ | ---------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------- |
| `POST /api/v1/inbox/tickets/:id/attachments` (register)                        | `ATTACHMENT_TOO_LARGE` (422) | `size_bytes` over 25 MiB per attachment                               | Compress or split the file                                  |
| `POST /api/v1/inbox/tickets/:id/attachments/:attId/content` (multipart upload) | `ATTACHMENT_TOO_LARGE` (413) | Buffered bytes over 25 MiB                                            | Same — shrink the file                                      |
| Audio voice-upload endpoints (e.g. a custom prompt or clip upload)             | `AUDIO_TOO_LARGE` (400/413)  | Audio file over the endpoint's cap — 2 MB on the voice upload surface | Re-encode at a lower bitrate, or trim                       |
| Voice-biometrics enrollment / verify sample                                    | `AUDIO_TOO_LARGE` (400)      | Sample over 30 seconds / 2 MB                                         | Trim the clip — a usable voiceprint is seconds, not minutes |

The limit differs per surface because the downstream consumer differs:
a ticket attachment lands in object storage, while an audio clip goes
straight to a media or biometrics pipeline that decodes it in memory.
Always read the size limit for the exact endpoint in its
[API reference](/api-reference) entry — the cap in the error message is
the byte ceiling for the surface you hit, stated in bytes.

If you instead received `ATTACHMENT_STORAGE_UNAVAILABLE` (503) on a
ticket upload, that is **not** a size cap — the file passed every
intake check and the storage write failed. Route to the
[attachment storage unavailable runbook](/troubleshooting/attachment-storage-unavailable)
instead of this page.

## 2. Diagnose the rejection

Work the response before touching the file:

1. **Read the `code`.** `ATTACHMENT_TOO_LARGE` means a byte ceiling;
   `UNSUPPORTED_MEDIA_TYPE` (422/415) means a content-type or multipart
   problem — shrinking the file will not clear a type rejection.
2. **Read the `message`.** It states the exact ceiling in bytes that
   tripped. Compare it against the file size you sent.
3. **Check where the cap fired.** On the ticket-attachment register
   call the check runs against the declared `size_bytes` in your JSON
   body; on the multipart upload call it runs against the actual bytes
   received. A mismatch between the two (declared under, actual over)
   fails at the upload step.
4. **Confirm the retry shape.** Retry with the same bytes and you get
   the same code, every time — the check is deterministic. Only a
   smaller payload changes the outcome.

## 3. Fix: bring the payload under the cap

* **Ticket attachments (25 MiB).** Compress the file first: a PDF
  re-exported with compression, an image resized to its display
  resolution, or a screen recording re-exported at a lower bitrate
  usually drops well under the ceiling. For genuinely larger evidence
  (long recordings, full log dumps), split the file into parts and
  attach them as separate uploads, or put the file in your own cloud
  storage and paste a link into the ticket reply — the message thread
  carries the reference and the cap never engages.
* **Audio uploads (2 MB class).** Re-encode, not just rename. A stereo
  44.1 kHz WAV at 1411 kbps becomes mono 16 kHz MP3 in the tens of
  kbps — indistinguishable for prompts and IVR audio. Any encoder
  (e.g. `ffmpeg -i in.wav -ac 1 -b:a 64k out.mp3`) gets a minute of
  speech comfortably under 2 MB.
* **Voice-biometrics samples (30 s / 2 MB).** Trim the clip. The
  enrollment verifier needs a few seconds of clean speech; long
  silences, intros, or repeated phrases only burn the cap. On this
  surface the cap is **both** a duration and a byte check, so shorten
  the recording rather than compressing it.

After shrinking, retry the same call once. The register + upload
sequence for ticket attachments is two calls; resend the register call
with the corrected `size_bytes` after the upload succeeds.

## 4. What not to do

* **Do not retry the identical payload.** The cap check runs before any
  storage write, so a repeat call re-rejects identically and only
  burns rate-limit budget.
* **Do not rename or container-swap the file.** Wrapping the same
  bytes in a `.zip` or changing the extension does not reduce the
  measured size, and on the register call a renamed mismatch between
  `content_type` and the actual bytes can move you into
  `UNSUPPORTED_MEDIA_TYPE`.
* **Do not treat `ATTACHMENT_STORAGE_UNAVAILABLE` (503) as this
  page's problem.** A 503 means validation passed and storage failed;
  a 422/413 here means validation failed. The remediation directions
  are opposite — retry the same file for the former, shrink it for
  the latter.

## 5. Escalation payload

You should be able to clear this class on your side — the cap is
tenant-owned input hygiene, not a platform fault. Escalate only if the
response you see contradicts the file you sent (e.g. a 4 MB file
rejected as over-limit), and include:

1. Your **tenant id** (dashboard → Settings → Organization, or
   `organizationId` from `GET /api/v1/me`).
2. The **endpoint** you called and the **object id** — the ticket id,
   or the voice-biometrics session/sample id.
3. The **file size in bytes** you sent (and the declared `size_bytes`
   on the register call, if different).
4. The full **error envelope**, including `meta.request_id` from the
   failed response.

That set lets support replay the exact validation decision instead of
re-measuring your file from a description.

## See also

* [Troubleshooting: ATTACHMENT\_STORAGE\_UNAVAILABLE](/troubleshooting/attachment-storage-unavailable)
  — the 503 storage-fault sibling on the same ticket-upload surface.
* [Troubleshooting: fan-out and upload rejections](/troubleshooting/fan-out-and-upload-errors)
  — the wider upload-validation cluster (`INVALID_FILE_TYPE`,
  `INVALID_AUDIO`, `MAGIC_BYTE_MISMATCH`) that sits beside these two
  size codes.
* [Troubleshooting: MEDIA\_UPLOAD\_FAILED](/troubleshooting/media-upload-failed)
  — the 502-class upload/download failures where the platform, not
  your payload, is the problem.
* [Error codes reference](/reference/error-codes) — the envelope and
  per-code table entries for both codes.