Errors

The API uses standard HTTP status codes and returns a consistent JSON error format. All error responses include an error code and a human-readable message.

Error Response Format

{
    "error": "error_code",
    "message": "Human-readable description of what went wrong."
}

Some errors include additional fields with context-specific information (e.g. credits_required for insufficient credits).

Error Codes

Detailed Error Responses

401 Unauthenticated

Returned when the Authorization header is missing, malformed, or contains an invalid token.

{
    "message": "Unauthenticated."
}

Resolution: Verify your token is correct and has not been revoked. See Authentication.

402 Insufficient Credits

Returned when the workspace does not have enough credits to perform the conversion.

{
    "error": "insufficient_credits",
    "message": "Insufficient credits for this conversion.",
    "credits_required": 2,
    "credits_available": 1
}

The response includes the number of credits required and currently available, so you can display a meaningful message to your users.

Resolution: Add more credits or upgrade your plan.

404 Not Found

Returned when a conversion UUID does not exist or belongs to a different workspace.

{
    "error": "not_found",
    "message": "Conversion not found."
}

Resolution: Verify the conversion ID is correct and was created using a token from the same workspace.

422 Conversion Failed

Returned when a sync conversion encounters an error during processing. The file format may be corrupted, unsupported, or unreadable.

{
    "error": "conversion_failed",
    "message": "Unable to extract text from the provided file."
}

Resolution: Verify the file is not corrupted and is in a supported format. If the file is a scanned document or image, try enabling use_enhanced_ai.

413 Payload Too Large

Returned when the uploaded file exceeds your plan's maximum file size limit. This is a server-level limit that applies before file validation.

{
    "message": "The POST data is too large."
}

Resolution: Reduce the file size before uploading. Check your plan's file size limit.

429 Rate Limited

Returned when the workspace has exceeded its per-minute rate limit.

{
    "message": "Too Many Attempts."
}

Resolution: Wait for the duration specified in the Retry-After header before retrying. See Rate Limits.

Validation Errors

If request parameters fail validation, the API returns a 422 response with field-level error details:

{
    "message": "The file field is required.",
    "errors": {
        "file": ["The file field is required."],
        "webhook_url": ["The webhook URL must be a valid URL."]
    }
}

Common validation errors:

Auto-Refund on Failure

Markdown Anything charges credits upfront when a conversion request is accepted. If the conversion fails for any reason, credits are automatically refunded to the workspace balance.

This applies to both sync and async conversions:

• Sync: Credits are refunded immediately and the 422 response is returned.
• Async: Credits are refunded when the background job fails. Check the conversion status via GET /conversions/{id}.