API & MCP

Errors and limits

The status codes the API returns, what each one means, and the ceilings on a single source.

In short

The v1 API returns 401 for a missing or invalid key, 402 when the account is out of credits, 403 when a request asks for a pro-only feature on a free account, 400 or 422 for bad parameters or a link Pepys cannot resolve, and 429 when you are rate limited – with a Retry-After header telling you how long to wait.

Status codes

401 – the key is missing or invalid. Check the Authorization header carries a current pk_live_ key from Settings → API keys.

402 – the account is out of credits. Top up, or enable auto-reload so an unattended job does not pause at a zero balance.

403 – the request asked for a pro-only feature (for example diarize: true) on an account that has never made a purchase. The body carries { "upgrade": true }; any credit purchase unlocks it permanently, not a subscription.

400 and 422 – bad parameters, or a link the API cannot resolve into media. A social or podcast link that has been deleted, made private, or is region-locked lands here.

429 – you are being rate limited. The response includes a Retry-After header; back off for that long rather than retrying immediately.

Ceilings on a single source

A clip generated for social is capped at 90 seconds. Uploads are capped by account: 1 GB on a free account and 5 GB once credits have been purchased, which is comfortably more than an hour-long lossless recording.

The platform's own ceiling on a single recording is 10 hours. Beyond that, split the file before sending it.

Retrying safely

Retry 429 and 5xx responses with backoff, and send an Idempotency-Key on the create call so a retried request returns the original job instead of starting a second transcription.

Do not retry 400, 401, 402, 403, or 422 unchanged: each one means the request or the account needs fixing first.

Errors and limits – questions, answered

What does a 402 from the Pepys API mean?

The account is out of credits. Top up in the app or turn on auto-reload, since a request cannot be accepted against an empty balance.

Which errors are worth retrying?

429 rate limits and 5xx responses, ideally with an Idempotency-Key so a retry returns the original job. A 400, 401, 402, 403, or 422 needs the request or account fixed first.

What does a 403 from the Pepys API mean?

The request asked for a pro-only feature, such as diarize: true, on an account that has never made a purchase. The body carries { "upgrade": true }; any credit purchase unlocks it for good.

How do I handle rate limiting?

The 429 response includes a Retry-After header. Wait that long before retrying rather than retrying in a tight loop.

What is the file size limit for the API?

1 GB on a free account and 5 GB once credits have been purchased, with a platform ceiling of 10 hours on a single recording.

Why can't the API resolve my link?

That returns 400 or 422. The usual causes are a deleted, private, or region-locked source, or a URL that is not a supported media or feed link.

Try it on your own audio

Create a free account and transcribe a recording – 60 minutes are included, no card required. Still stuck? Email contact@pepys.co or see the support page.