---
title: "Error codes"
description: "All 34 error codes of the markitdown.ai API v1 in one table: HTTP status, meaning, whether to retry, and what to do."
url: https://markitdown.ai/docs/errors
updated: 2026-09-26
source: markitdown.ai
---

# Error codes

> All 34 error codes of the markitdown.ai API v1 in one table: HTTP status, meaning, whether to retry, and what to do.

## Error format

Errors are `application/problem+json`. Branch on `error` (the code below); `detail` explains this particular failure and `retryable` says whether repeating the same request can succeed. `429` and `503` also send `Retry-After`.

**402 example**

```json
{
  "type": "https://markitdown.ai/docs/errors/insufficient_credits",
  "title": "Insufficient credits",
  "status": 402,
  "detail": "Insufficient credits",
  "instance": "/v1/convert/pdf",
  "error": "insufficient_credits",
  "message": "Insufficient credits",
  "request_id": "00000000-0000-4000-8000-000000000002",
  "retryable": false,
  "hint": "Upgrade the plan or reduce the requested work."
}
```

## All error codes

| Code | Status | Meaning | Retry | What to do |
| --- | --- | --- | --- | --- |
| `invalid_request` | 400 | Invalid request | No | Check the request fields and types. |
| `invalid_input` | 400 | Invalid input | No | Provide exactly one supported input. |
| `url_not_allowed` | 400 | URL not allowed | No | Use a public HTTP or HTTPS URL. |
| `invalid_webhook_url` | 400 | Invalid webhook URL | No | Use a public https URL that does not resolve to a private or reserved address. |
| `schema_unsupported` | 400 | Schema unsupported | No | Use the documented JSON Schema subset. |
| `unauthorized` | 401 | Unauthorized | No | Send a valid API key in x-api-key. |
| `insufficient_credits` | 402 | Insufficient credits | No | Upgrade the plan or reduce the requested work. |
| `forbidden` | 403 | Forbidden | No | Check account access for this operation. |
| `scope_missing` | 403 | Scope missing | No | Create a key with the required scope. |
| `subscription_required` | 403 | Subscription required | No | Subscribe to Lite, Pro, or Max to use conversions. |
| `upload_limit_exceeded` | 403 | Upload limit exceeded | No | Reduce stored files or upgrade the plan. |
| `not_found` | 404 | Not found | No | Check the resource identifier. |
| `job_not_terminal` | 409 | Job not terminal | Yes | Wait for the job to finish before reading its result. |
| `idempotency_conflict` | 409 | Idempotency conflict | No | Use a new Idempotency-Key for a different request body. |
| `upload_not_completed` | 409 | Upload not completed | No | Finish POST /v1/uploads/{id}/complete before referencing it, or start a new upload. |
| `upload_already_used` | 409 | Upload already used | No | Start a new upload; each completed upload can be submitted once. |
| `file_expired` | 410 | File expired | No | The referenced file's conversion has expired or been deleted; upload it again. |
| `upload_aborted` | 410 | Upload aborted | No | This upload was aborted and can never complete; start a new upload. |
| `upload_too_large` | 413 | Upload too large | No | Upload a smaller file. |
| `input_too_large` | 413 | Input too large | No | Reduce the input size. |
| `upload_type_unsupported` | 415 | Upload type unsupported | No | Use a supported document or media type. |
| `input_format_mismatch` | 415 | Input format mismatch | No | Send a format accepted by this endpoint. |
| `page_cap_exceeded` | 422 | Page cap exceeded | No | Reduce the page range or choose a plan with a higher cap. |
| `document_unprocessable` | 422 | Document unprocessable | No | Check whether the document is damaged or encrypted. |
| `url_fetch_failed` | 422 | URL fetch failed | Yes | Retry later or upload the page as a file. |
| `source_not_supported` | 422 | Source not supported | No | Upload the source file, subtitles, or pasted text instead. |
| `duration_cap_exceeded` | 422 | Duration cap exceeded | No | Use a shorter media file. |
| `rate_limited` | 429 | Rate limited | Yes | Retry after the indicated delay. |
| `concurrency_limited` | 429 | Concurrency limited | Yes | Retry after an active job finishes. |
| `internal_error` | 500 | Internal error | Yes | Retry with the same Idempotency-Key. |
| `parse_failed` | 500 | Parse failed | Yes | Retry or use another supported input. |
| `webhooks_unavailable` | 502 | Webhooks unavailable | Yes | Retry after the indicated delay; webhook management is temporarily unavailable. |
| `conversion_unavailable` | 503 | Conversion unavailable | Yes | Retry after the indicated delay. |
| `parser_unavailable` | 503 | Parser unavailable | Yes | Retry after the indicated delay. |

## Related

- [API reference](https://markitdown.ai/docs/api)
- [Errors & limits](https://markitdown.ai/docs/errors-and-limits)