How-to: Errors & Troubleshooting

Learn how to handle API errors, understand error responses, and troubleshoot common issues with the Intelliprint API.

Error Response Format

All API errors return a consistent JSON structure with an error object:

{
  "error": {
    "message": "Human-readable error description",
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "param": "testmood"
  }
}

Error Object Fields

Field	Description
`message`	Human-readable error message (safe to display to users)
`type`	General error category
`code`	Specific error code
`param`	The parameter that caused the error (if applicable)

Error Types

`invalid_request_error`

Your request has invalid parameters or is malformed. Common causes:

Missing required parameters
Invalid parameter values
Unknown parameters (typos)
Incorrectly formatted data

`authentication_error`

Issues with your API key or authentication. Common causes:

No API key provided
Invalid API key
API key has been revoked
Logged out session (dashboard use)

`payment_error`

Issues with account billing or payment. Common causes:

Insufficient account balance
Payment method issues
Account billing problems

`rate_limited`

Too many requests in a short time period. Solution: Implement exponential backoff and retry logic.

`internal_error`

Something went wrong on Intelliprint’s servers. Solution: Retry the request. If persists, contact support.

Error Codes

Parameter Errors

`parameter_invalid`

A parameter has an invalid value.

{
  "error": {
    "message": "The postage service 'super_fast' is not valid. Valid options are: uk_second_class, uk_first_class, etc.",
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "param": "postage.service"
  }
}

`parameter_missing`

A required parameter is missing.

{
  "error": {
    "message": "Missing required parameter: You must provide either 'content', 'file', or 'template'",
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "param": "content"
  }
}

`parameter_unknown`

An unknown parameter was provided (likely a typo).

{
  "error": {
    "message": "Received unknown parameter: testmood (Did you mean testmode?)",
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "param": "testmood"
  }
}

Authentication Errors

`no_api_key`

No API key was provided.

{
  "error": {
    "message": "No API key provided. Include your API key in the Authorization header",
    "type": "authentication_error",
    "code": "no_api_key"
  }
}

`invalid_api_key`

The provided API key is invalid or has been revoked.

{
  "error": {
    "message": "Invalid API key provided. Check your API key at account.intelliprint.net/api_keys",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Data Errors

`body_too_large`

Request body exceeds size limits.

{
  "error": {
    "message": "Request body is too large. Maximum size is 50MB",
    "type": "invalid_request_error",
    "code": "body_too_large"
  }
}

`body_incorrect_format`

Request body format is invalid (not valid JSON or multipart/form-data).

{
  "error": {
    "message": "Request body must be valid JSON or multipart/form-data",
    "type": "invalid_request_error",
    "code": "body_incorrect_format"
  }
}

Resource Errors

`not_found`

The requested resource doesn’t exist.

{
  "error": {
    "message": "No print job found with ID 'print_xyz789'",
    "type": "invalid_request_error",
    "code": "not_found"
  }
}

`forbidden`

You don’t have permission to access this resource.

{
  "error": {
    "message": "You do not have permission to access this resource",
    "type": "authentication_error",
    "code": "forbidden"
  }
}

Rate Limiting

`rate_limited`

Too many requests in a short period.

{
  "error": {
    "message": "Rate limit exceeded. Please wait before making more requests",
    "type": "rate_limited",
    "code": "rate_limited"
  }
}

Payment Errors

`payment_error`

Issues with account billing or balance.

{
  "error": {
    "message": "Insufficient account balance. Please add funds to your account",
    "type": "payment_error",
    "code": "payment_error"
  }
}

Error Handling Best Practices

Comprehensive Error Handler

async function handleApiRequest(requestFn) {
  try {
    return await requestFn();
  } catch (error) {
    // Log for debugging
    console.error('API Error:', {
      type: error.type,
      code: error.code,
      message: error.message,
      param: error.param
    });
    
    // Handle specific errors
    switch (error.type) {
      case 'invalid_request_error':
        // Show user-friendly message
        throw new Error(`Invalid request: ${error.message}`);
        
      case 'authentication_error':
        // Critical - likely needs new API key
        throw new Error('Authentication failed. Check API key.');
        
      case 'payment_error':
        // Notify about billing
        throw new Error('Payment required. Add funds to account.');
        
      case 'rate_limited':
        // Retry with backoff
        throw new Error('Rate limited. Please try again shortly.');
        
      case 'internal_error':
        // Retry or contact support
        throw new Error('Server error. Please retry or contact support.');
        
      default:
        throw new Error(`API error: ${error.message}`);
    }
  }
}

// Usage
const printJob = await handleApiRequest(() => 
  ip.prints.create({/* ... */})
);

Retry Logic

async function retryApiCall(fn, maxRetries = 3) {
  let lastError;
  
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;
      
      // Only retry on rate limits or internal errors
      const shouldRetry = [
        'rate_limited',
        'internal_error'
      ].includes(error.code);
      
      if (!shouldRetry || i === maxRetries - 1) {
        throw error;
      }
      
      // Exponential backoff
      const delay = Math.pow(2, i) * 1000;
      console.log(`Retrying in ${delay}ms... (attempt ${i + 1}/${maxRetries})`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  
  throw lastError;
}

Common Issues

'parameter_unknown: testmood'

Error: Received unknown parameter: testmood (Did you mean testmode?)Cause: Typo in parameter nameSolution: Check spelling - it’s testmode not testmood

No print job created but no error

Issue: API returns success but nothing appearsCause: Created as unconfirmed draftSolution: Set confirmed: true to submit for printing

const printJob = await ip.prints.create({
  /* ... */,
  confirmed: true  // Don't forget this!
});

Address not showing in envelope window

Issue: Address doesn’t appear in envelope windowCauses:

Using dynamic addresses with wrong settings
Address positioned incorrectly in PDF
Wrong envelope window side selected

Solutions:

Check address positioning (20mm from left, 45mm from top)
Use nudge parameter for fine-tuning
Verify address_window setting (left/right)

Learn more →

Cost values seem wrong

Issue: Cost shows as £54,000,000Cause: Not converting from 8-decimal precisionSolution: Divide by 100,000,000

const cost = printJob.cost.after_tax / 100000000;  // £0.54

Learn more →

Cannot cancel print job

Issue: Cancellation fails or only partially succeedsCauses:

Letters already in printing status
Letters already shipped

Solution: Cancel as soon as possible after creation. Once printing starts, cancellation is no longer possible.

Debugging Tips

1. Enable Detailed Logging

// Log all API requests and responses
const ip = Intelliprint('your-api-key-here', {
  debug: true  // If SDK supports it
});

// Or manual logging
try {
  const result = await ip.prints.create(data);
  console.log('Success:', JSON.stringify(result, null, 2));
} catch (error) {
  console.error('Error:', JSON.stringify(error, null, 2));
}

2. Test with Minimal Example

Start with the simplest possible request:

const test = await ip.prints.create({
  testmode: true,
  content: '<h1>Test</h1>',
  recipients: [{
    address: {
      name: 'Test User',
      line: '123 Test St',
      postcode: 'SW1A 1AA',
      country: 'GB'
    }
  }]
});

3. Check API Response Status

// Raw HTTP request for debugging
const response = await fetch('https://api.intelliprint.net/v1/prints', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
});

console.log('Status:', response.status);
const body = await response.json();
console.log('Body:', body);

4. Use Test Mode

Always test with testmode: true first:

const printJob = await ip.prints.create({
  testmode: true,  // Free, not sent, full API behaviour
  /* ... rest of your data ... */
});

Getting Help

If you’re still experiencing issues:

Check API Reference: docs.intelliprint.net/api
Review Examples: Check our quickstart guides
Contact Support: Email [email protected] with:
- Error message and code
- Request details (sanitized)
- Expected vs actual behaviour
- Print job ID (if applicable)

Contact Support

We’re here to help! Email [email protected] with any questions

Next Steps

Track & Retrieve

Monitor your print jobs

Understand Costs

Learn about cost calculation

Overview & Concepts

Review core concepts

API Reference

Full API documentation

Getting Started

Quickstarts

Use Cases

Tutorials

How-to Guides

SDK Reference

Reference

Resources

​Error Response Format

​Error Object Fields

​Error Types

​invalid_request_error

​authentication_error

​payment_error

​rate_limited

​internal_error

​Error Codes

​Parameter Errors

​parameter_invalid

​parameter_missing

​parameter_unknown

​Authentication Errors

​no_api_key

​invalid_api_key

​Data Errors

​body_too_large

​body_incorrect_format

​Resource Errors

​not_found

​forbidden

​Rate Limiting

​rate_limited

​Payment Errors

​payment_error

​Error Handling Best Practices

​Comprehensive Error Handler

​Retry Logic

​Common Issues

​Debugging Tips

​1. Enable Detailed Logging

​2. Test with Minimal Example

​3. Check API Response Status

​4. Use Test Mode

​Getting Help

Contact Support

​Next Steps

Track & Retrieve

Understand Costs

Overview & Concepts

API Reference

Error Response Format

Error Object Fields

Error Types

`invalid_request_error`

`authentication_error`

`payment_error`

`rate_limited`

`internal_error`

Error Codes

Parameter Errors

`parameter_invalid`

`parameter_missing`

`parameter_unknown`

Authentication Errors

`no_api_key`

`invalid_api_key`

Data Errors

`body_too_large`

`body_incorrect_format`

Resource Errors

`not_found`

`forbidden`

Rate Limiting

`rate_limited`

Payment Errors

`payment_error`

Error Handling Best Practices

Comprehensive Error Handler

Retry Logic

Common Issues

Debugging Tips

1. Enable Detailed Logging

2. Test with Minimal Example

3. Check API Response Status

4. Use Test Mode

Getting Help

Next Steps