All API errors follow a consistent JSON format to help you handle them programmatically:
{
"error": "error_code",
"message": "Human-readable error description",
"details": {
"field": "specific field causing the error (if applicable)",
"code": "internal_error_code",
"suggestion": "Recommended action to resolve the error"
},
"request_id": "unique_request_identifier_for_support"
}The request was invalid or cannot be served
Authentication failed or API key is invalid
Access denied due to insufficient permissions
The requested resource was not found
Request is well-formed but contains semantic errors
Rate limit exceeded
An unexpected error occurred on our servers
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error": "invalid_api_key",
"message": "The provided API key is invalid or has expired",
"details": {
"code": "AUTH_001",
"suggestion": "Please check your API key and ensure it's correctly set in the X-API-Key header"
},
"request_id": "req_1234567890abcdef"
}HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_file_format",
"message": "The uploaded file format is not supported",
"details": {
"field": "file",
"code": "FILE_001",
"suggestion": "Please upload a supported format: PDF, DOCX, XLSX, PPTX, HTML, or TXT",
"supported_formats": ["pdf", "docx", "xlsx", "pptx", "html", "txt"]
},
"request_id": "req_abcdef1234567890"
}HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
{
"error": "rate_limit_exceeded",
"message": "You have exceeded the rate limit for your plan",
"details": {
"code": "RATE_001",
"suggestion": "Please wait 60 seconds before making another request",
"retry_after": 60,
"limit": "100 requests per minute",
"reset_time": "2024-01-15T10:31:00Z"
},
"request_id": "req_fedcba0987654321"
}Exponential Backoff: Implement exponential backoff for 5xx errors and 429 rate limits.
Retry Limits: Don't retry 4xx errors (except 429). Set maximum retry attempts.
Respect Headers: Use Retry-After header values when provided.
curl --retry 3 \ --retry-delay 5 \ --retry-connrefused \ -X POST https://api.markdownconverters.com/api/v1/convert
Request ID: Always log the request_id for support issues.
Context: Include relevant request parameters in your logs.
Monitoring: Set up alerts for high error rates or specific error types.
X-API-Key headerWhen contacting support, please include:
request_id from the error responseSuccessful responses include the converted content and metadata:
{
"job_id": "conv_1234567890abcdef",
"status": "completed",
"markdown_content": "# Document Title\n\nConverted content...",
"metadata": {
"original_filename": "document.pdf",
"file_size": 1024000,
"pages_processed": 5,
"processing_time": 12.34,
"ocr_confidence": 0.95
},
"request_id": "req_1234567890abcdef"
}