Errors

This page explains all error codes you might encounter when using the Docstron API, along with common causes and solutions.

Error Response Format

All error responses from the Docstron API follow this structure:

{
  "success": false,
  "message": "Error description",
  "data": []
}

For validation errors, an additional errors array is included:

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "field_name",
      "message": "Error description",
      "type": "error_type"
    }
  ]
}

HTTP Status Codes

400 - Bad Request

The request was invalid or cannot be processed due to client error.

Missing Required Fields

{
  "success": false,
  "message": "No fields provided to update.",
  "data": []
}

When it occurs:

Updating a template or document without providing any data
Empty request body for endpoints that require data

Solution:

Ensure all required fields are included in your request
Verify the request body is not empty

Subscription Limit Reached

{
  "success": false,
  "message": "You've reached the maximum monthly limit of 20 documents for your subscription.",
  "data": []
}

When it occurs:

You’ve exceeded your plan’s monthly document generation limit

Solution:

Upgrade your subscription at docstron.com/pricing
Wait until your monthly limit resets

401 - Unauthorized

Authentication failed or API key is invalid.

Invalid API Key

{
  "detail": "Invalid API key"
}

When it occurs:

The API key is incorrect or has been revoked
API key has been regenerated and old key is being used

Solution:

Verify your API key at docstron.com/api-keys
Generate a new API key if needed
Check for typos in the Authorization header

Missing API Key

{
  "detail": "Not authenticated"
}

When it occurs:

No Authorization header is included in the request
Authorization header is malformed

Solution:

Add the Authorization header: Authorization: Bearer YOUR_API_KEY
Ensure the Bearer token format is correct

404 - Not Found

The requested resource does not exist.

Application Not Found

{
  "success": false,
  "message": "Application not found.",
  "data": []
}

When it occurs:

Invalid or non-existent application_id
Application has been deleted
Application belongs to a different account

Solution:

Verify the application_id is correct
List all applications using the Get All Applications endpoint
Ensure you’re using the correct API key for the account

Template Not Found

{
  "success": false,
  "message": "Template not found.",
  "data": []
}

When it occurs:

Invalid or non-existent template_id
Template has been deleted
Template belongs to a different application

Solution:

Verify the template_id is correct
Check if the template still exists using the Get Template endpoint
Ensure the template hasn’t been deleted

Template Not Found (Generation)

{
  "success": false,
  "message": "Template not found. Please ensure application and template are active.",
  "data": []
}

When it occurs:

Template exists but is marked as inactive
Application is marked as inactive
Template or application has been deleted

Solution:

Verify both the template and application are active
Update template status using Update Template
Check application status in the dashboard

Document Not Found

{
  "success": false,
  "message": "Document not found.",
  "data": []
}

When it occurs:

Invalid or non-existent document_id
Document has been deleted
Document belongs to a different account

Solution:

Verify the document_id is correct
Check if the document still exists
Ensure you’re using the correct API key for the account

422 - Unprocessable Entity

The request was well-formed but contains semantic errors.

Validation Error

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "response_type",
      "message": "Input should be 'pdf', 'json_with_base64' or 'document_id'",
      "type": "literal_error"
    }
  ]
}

When it occurs:

Invalid value for response_type in document generation
Field values don’t match expected types or formats
Invalid enum values

Solution:

Check the errors array for specific field issues
Ensure values match the allowed options
Valid response_type values: pdf, json_with_base64, document_id

500 - Internal Server Error

An unexpected error occurred on the server.

Template Engine Error

{
  "success": false,
  "message": "Template engine error!",
  "data": []
}

When it occurs:

Template rendering fails
Missing required data for template placeholders
Invalid placeholder syntax in template
Circular dependencies in template logic

Solution:

Verify all template placeholders have corresponding data
Check template syntax for errors
Ensure the data object includes all required fields
Test template with sample data

Document Creation Failed

{
  "success": false,
  "message": "Failed to create the document",
  "data": []
}

When it occurs:

PDF generation service is unavailable
Temporary server issue
Database error during document storage

Solution:

Wait a few moments and retry the request
If persistent, contact support@docstron.com
Check the status page for service updates

Failed to Get Applications

{
  "success": false,
  "message": "Failed to get all the applications.",
  "data": []
}

When it occurs:

Database connectivity issue
Temporary server problem

Solution:

Wait and retry the request
If persistent, contact support@docstron.com

Failed to Get Application

{
  "success": false,
  "message": "Failed to get the application.",
  "data": []
}

When it occurs:

Database connectivity issue
Temporary server problem

Solution:

Wait and retry the request
If persistent, contact support@docstron.com

Failed to Get Template

{
  "success": false,
  "message": "Failed to get the template.",
  "data": []
}

When it occurs:

Database connectivity issue
Temporary server problem

Solution:

Wait and retry the request
If persistent, contact support@docstron.com

Failed to Update Template

{
  "success": false,
  "message": "Failed to update the template.",
  "data": []
}

When it occurs:

Database connectivity issue
Temporary server problem during update

Solution:

Wait and retry the request
If persistent, contact support@docstron.com

Failed to Delete Template

{
  "success": false,
  "message": "Failed to delete the template.",
  "data": []
}

When it occurs:

Database connectivity issue
Temporary server problem during deletion

Solution:

Wait and retry the request
If persistent, contact support@docstron.com

Failed to Get Document

{
  "success": false,
  "message": "Failed to get the document.",
  "data": []
}

When it occurs:

Database connectivity issue
Temporary server problem

Solution:

Wait and retry the request
If persistent, contact support@docstron.com

Failed to Update Document

{
  "success": false,
  "message": "Failed to update the document.",
  "data": []
}

When it occurs:

Database connectivity issue
Temporary server problem during update

Solution:

Wait and retry the request
If persistent, contact support@docstron.com

Common Error Scenarios

Authentication Issues

Problem: Getting 401 errors consistently

Checklist:

✅ API key is correct and copied completely
✅ Authorization header format: Authorization: Bearer YOUR_API_KEY
✅ API key hasn’t been revoked or regenerated
✅ Using the correct API key for the account
✅ No extra spaces or characters in the key

Resource Not Found

Problem: Getting 404 errors for existing resources

Checklist:

✅ ID is copied correctly (no typos)
✅ Resource hasn’t been deleted
✅ Resource belongs to the correct account
✅ For templates/applications: Check if they’re active
✅ Using the correct API endpoint URL

Document Generation Fails

Problem: Getting 500 errors during PDF generation

Checklist:

✅ Template contains all required placeholders
✅ Data object includes values for all placeholders
✅ Template HTML/CSS syntax is valid
✅ Template is marked as active
✅ Application is marked as active
✅ Not exceeding monthly document limit

Validation Errors

Problem: Getting 422 validation errors

Checklist:

✅ All required fields are included
✅ Field values match expected types
✅ Enum values are spelled correctly (e.g., response_type)
✅ JSON is properly formatted
✅ No extra or misspelled fields

Need Help?

If you’re experiencing errors that aren’t covered here or need assistance:

📧 Email: support@docstron.com
📚 Documentation: API Reference
💬 Live Support: Available in your dashboard
🐛 Report Issues: Include error details, request/response, and timestamps

When reporting errors, please include:

Complete error response
The API endpoint you were calling
Request body (remove sensitive data)
Timestamp of the error
Your application/template IDs (if applicable)