---
title: "Errors & limits"
description: "Problem+json errors, per-plan rate limits, idempotency, and the v1 usage and formats endpoints."
url: https://markitdown.ai/docs/errors-and-limits
updated: 2026-09-28
source: markitdown.ai
---

# Errors & limits

> Problem+json errors, per-plan rate limits, idempotency, and the v1 usage and formats endpoints.

## Error format

Errors are `application/problem+json`. `error` is a stable machine code, `type` is a URL to that code's docs page, and `status`, `title`, `detail`, `hint`, `retryable`, and `request_id` explain what happened and whether a retry can help. Quote the `request_id` when you contact support.

**Common responses**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `200 / 202` | OK | no | Done, or accepted as a background conversion. |
| `400` | invalid_request | no | Body or query failed validation. |
| `401` | unauthorized | no | Missing, revoked, or expired API key. |
| `402` | insufficient_credits | no | Not enough credits left. |
| `403` | subscription_required / forbidden | no | No active Lite/Pro/Max subscription, or an API key on a non-v1 path. |
| `409` | idempotency_conflict | no | The `Idempotency-Key` was reused with a different request body. |
| `410` | file_expired | no | A referenced `file` belongs to a conversion that has expired or been deleted. |
| `413 / 415 / 422` | input errors | no | Too large, unsupported type, or a document that cannot be parsed. |
| `429` | rate_limited / concurrency_limited | no | Too many requests or waiting conversions at once; retry after `Retry-After`. |
| `503` | parser_unavailable | no | A dependency is temporarily unavailable; retry. |

- [Error codes](/docs/errors) — every code with retry guidance
- [API reference](/docs/api) — responses per operation

## Rate limits & idempotency

Requests are rate limited per API key and account: Lite 20, Pro 40, and Max 60 requests per minute. Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`; a 429 adds `Retry-After`.

Every `POST /v1/convert/{name}` and `/v1/convert/markdown/{name}` endpoint accepts an `Idempotency-Key`. A retry with the same key and body within 24 hours replays the original response; the same key with a different body returns `409 idempotency_conflict`, and a retry while the first request is still in flight waits behind it rather than starting a second conversion.

Deleting a conversion removes it from your library at once and erases its stored files within an hour; a source file shared with another conversion is kept until that one is deleted too. Deleting your account erases all your stored source and result files.

## Usage and formats

**GET** `/v1/usage` — Plan, credit balance, quota, reset time, and recent charges

**GET** `/v1/formats` — The name catalog, input kinds, credit routes, and your plan's limits

## Free conversions on the website

- Without an account, the website converter allows 3 conversions an hour and 10 a day per IP address.
- Signed in, the website converter and the playground on these pages share 20 free conversions a day per account, with no hourly limit. After that they use your credits.
- API keys are always billed; the free allowance applies only to the signed-in website.

## What are the real API key rate limits?

Requests are rate limited per API key and account: Lite 20, Pro 40, and Max 60 requests per minute. These numbers come from each plan's `rateLimitPerMinute` field. There is no separate daily request quota on API keys. API access requires a paid subscription: a key only works while its account holds an active Lite, Pro, or Max subscription (`403 subscription_required` otherwise). Waiting conversions are also limited per account (Lite 3, Pro 5, Max 8 at once); beyond that a call returns `429 concurrency_limited`.

Lite allows 20 requests per minute. Pro allows 40. Max allows 60. Each plan has its own per-file size limit — Lite 100 MB, Pro 200 MB, Max unlimited (bounded by credits and storage instead) — enforced the same way on the website and the public API. A single `multipart/form-data` request tops out at 100 MB regardless of plan (Cloudflare's request-body limit on our zone); a file within your plan's limit but over that uses `POST /v1/uploads` instead (see below), which is unrelated to OCR and exists only to get the bytes past that transport ceiling.

## How does idempotency work with a 429?

A 429 is a rate-limit response, not a conversion failure, and nothing was charged. Wait for `Retry-After`, then retry the same request with the same `Idempotency-Key`. If an earlier attempt was accepted, the replay returns its original response instead of starting a second conversion. `GET /v1/usage` shows your balance and recent charges if you need to confirm what was spent.

## Related

- [URL fetcher](https://markitdown.ai/docs/fetcher)
- [Introduction](https://markitdown.ai/docs)
- [Document Conversion APIs](https://markitdown.ai/developers)