Error codes
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.
{
"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. |
Sources and specs: RFC 9110: HTTP Semantics · RFC 7763: The text/markdown Media Type