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

# Maybloc API errors, rate limits and idempotency

> Every error code the API returns, what it means and how to fix it, plus the per-key rate limit, idempotency keys, and recording size and length limits.

## What does an error response look like?

Errors return an HTTP status code and a JSON body:

```json theme={null}
{ "error": { "code": "insufficient_credit", "message": "Your balance is too low for this recording.", "request_id": "req_…" } }
```

Quote the `request_id` when you contact support.

## Which error codes does the API return?

| Status | Code | Meaning |
| - | - | - |
| 400 | `invalid_request` | A field is missing or out of range. |
| 401 | `authentication_required` | Missing or invalid API key. |
| 402 | `insufficient_credit` | Your balance is too low for this recording. |
| 403 | `forbidden` | Read-only key, or a request from another site. |
| 404 | `not_found` | No such upload or transcript in your workspace. |
| 409 | `conflict` | Upload not complete, result not ready, or an Idempotency-Key reused for a different request. |
| 413 | `payload_too_large` | The file or request body is larger than allowed. |
| 415 | `unsupported_media_type` | The file type is not one we accept. |
| 429 | `rate_limited` | Too many requests. Wait for Retry-After seconds. |
| 500 | `internal_error` | We could not complete the request. Try again; quote the request id if it keeps happening. |

## What are the rate limits?

Each API key can make 300 requests a minute across all endpoints. Past that, requests return `429` with a `Retry-After` header giving the seconds to wait. Poll a transcript every few seconds, or use a [webhook](https://docs.maybloc.com/guides/webhooks.md) instead of polling.

## What are the limits on recordings?

* **Length:** 20 seconds to 3 hours. Outside that range `POST /transcripts` returns `400`.
* **Size:** up to 2 GB.
* **Formats:** MP3, M4A, AAC, WAV, FLAC, OGG, Opus or WebM audio, or MP4, MOV, MKV or WebM video (only the sound is kept).
* **Upload URL:** accepts one PUT for 15 minutes.

## How do idempotency keys work?

Send an `Idempotency-Key` header of 8 to 160 characters with `POST /transcripts`. Use a new key for each transcript you want. Repeating a request with the same key returns the same transcript and charges once. Reusing a key for a different request returns `409`.

## Is a failed transcript charged?

No. The price is held from your balance when you create a transcript and charged when it completes. Failed and canceled transcripts are not charged.


## Related topics

- [How to authenticate Maybloc API requests](https://docs.maybloc.com/authentication.md)
- [Maybloc API documentation](https://docs.maybloc.com/index.md)
- [Maybloc API pricing: per-minute rates and add-on prices](https://docs.maybloc.com/guides/pricing.md)
- [Transcribe a recording with the Maybloc API](https://docs.maybloc.com/quickstart.md)
- [Use the Maybloc docs with AI agents and coding assistants](https://docs.maybloc.com/guides/ai-agents.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.