Error Codes

Common error responses and how to handle them.

All errors return a JSON response with an error field describing the issue.

Error Response Format

{
  "error": "Error message describing the issue",
  "code": "ERROR_CODE",
  "status": 401
}

HTTP Status Codes

Error Details

400 Bad Request

Returned when the request is malformed or missing required parameters.

Common causes:

• Missing templateId parameter
• Missing variables object
• Invalid JSON in request body
• Missing required variables for the template

Example:

{
  "error": "Missing required parameter: templateId",
  "code": "BAD_REQUEST",
  "status": 400
}

How to fix:

• Ensure all required parameters are included
• Validate your JSON syntax
• Check that all template variables are provided

401 Unauthorized

Returned when authentication fails.

Common causes:

• Missing x-api-key header
• Invalid API key
• Expired API key

Example:

{
  "error": "Invalid API key",
  "code": "UNAUTHORIZED",
  "status": 401
}

How to fix:

• Include the x-api-key header in your request
• Verify your API key is correct
• Generate a new API key if the current one is expired

403 Forbidden

Returned when the request is authenticated but not allowed.

Common causes:

• Monthly quota exceeded
• Template belongs to another user
• Account suspended

Example:

{
  "error": "Monthly quota exceeded. Upgrade your plan to continue.",
  "code": "QUOTA_EXCEEDED",
  "status": 403
}

How to fix:

• Check your usage in the dashboard
• Upgrade your subscription plan
• Wait for the monthly quota to reset

404 Not Found

Returned when the requested resource doesn't exist.

Common causes:

• Template ID is incorrect
• Template was deleted
• Template UUID is malformed

Example:

{
  "error": "Template not found",
  "code": "NOT_FOUND",
  "status": 404
}

How to fix:

• Verify the template ID is correct
• Check that the template exists in your dashboard
• Ensure the UUID format is valid

500 Internal Server Error

Returned when an unexpected error occurs on the server.

Common causes:

• Server-side processing error
• Template rendering failure
• Storage service unavailable

Example:

{
  "error": "An unexpected error occurred during PDF generation",
  "code": "INTERNAL_ERROR",
  "status": 500
}

How to fix:

• Retry the request after a few seconds
• Check the status page for service outages
• Contact support if the issue persists

Error Handling Best Practices

1. Always Check Response Status

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${error.status}: ${error.error}`);
  // Handle specific error codes
  switch (error.status) {
    case 401:
      // Re-authenticate
      break;
    case 403:
      // Check quota
      break;
    case 404:
      // Template not found
      break;
    default:
      // Generic error handling
  }
}

2. Implement Retry Logic for 5xx Errors

async function generateWithRetry(templateId, variables, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await generatePDF(templateId, variables);
      return response;
    } catch (error) {
      if (error.status >= 500 && attempt < maxRetries) {
        await sleep(1000 * attempt); // Exponential backoff
        continue;
      }
      throw error;
    }
  }
}

3. Validate Before Sending

function validateRequest(templateId, variables) {
  if (!templateId) {
    throw new Error('templateId is required');
  }
  if (!variables || typeof variables !== 'object') {
    throw new Error('variables must be an object');
  }
  // Add more validation as needed
}