Error Handling

pdfRelay uses standard HTTP status codes and returns structured JSON error responses to help you diagnose and handle issues programmatically.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "success": false,
  "error": {
    "code": "INVALID_HTML",
    "message": "The provided HTML could not be parsed.",
    "details": {
      "line": 42,
      "column": 15,
      "snippet": "<div class='unclosed"
    }
  }
}

Field	Type	Description
`success`	boolean	Always `false` for errors
`error.code`	string	Machine-readable error code (see table below)
`error.message`	string	Human-readable explanation of the error
`error.details`	object \| null	Additional context (varies by error type)

Error Codes Reference

HTTP Status	Code	Description
400	`INVALID_REQUEST`	The request body is malformed or missing required fields
400	`INVALID_HTML`	The HTML content could not be parsed or rendered
400	`INVALID_OPTIONS`	One or more conversion options are invalid
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	The API key does not have permission for this action
404	`NOT_FOUND`	The requested resource (job, document, etc.) does not exist
409	`SLUG_CONFLICT`	The hosting slug is already in use
413	`PAYLOAD_TOO_LARGE`	The request body exceeds the maximum allowed size
429	`RATE_LIMITED`	Too many requests. Check rate limit headers.
429	`QUOTA_EXCEEDED`	Monthly conversion quota exhausted. Upgrade your plan.
500	`CONVERSION_ERROR`	An unexpected error occurred during conversion
503	`SERVICE_UNAVAILABLE`	The service is temporarily unavailable. Retry with backoff.

Structured Error Details

Some error codes include a details object with additional context:

Validation Errors

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Validation failed.",
    "details": {
      "fields": [
        { "field": "html", "message": "html is required" },
        { "field": "options.page_size", "message": "Invalid page size 'B5'. Must be one of: Letter, A4, A3, Legal, Tabloid" }
      ]
    }
  }
}

Rate Limit Errors

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "details": {
      "limit": 60,
      "remaining": 0,
      "reset_at": "2025-01-15T10:31:00Z",
      "retry_after": 12
    }
  }
}

Best Practices for Error Handling

Always check the success field before processing the response.
Use the error.code for programmatic handling rather than parsing the message string.
Retry on 429 and 503 errors with exponential backoff. Respect the Retry-After header.
Do not retry on 400 or 401 errors. These indicate a problem with your request that needs to be fixed.
Log the full error response including details to aid in debugging.