Error Codes

Understanding API errors and validation messages.

HTTP Status Codes

Code	Meaning	Description
`200`	OK	Request successful
`400`	Bad Request	Invalid JSON or missing required fields
`401`	Unauthorized	Missing or invalid API key
`402`	Payment Required	Monthly quota exceeded
`422`	Unprocessable Entity	Validation errors in request data
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Error	Server error (please report)

Error Response Format

All errors return a JSON object with details:

{
  "error": "validation_failed",
  "details": [
    {
      "path": "$.invoice.seller.vat_id",
      "code": "INVALID_VAT_FORMAT",
      "message": "VAT ID 'DE12345' invalid. Expected: country code + numbers (e.g., DE123456789)",
      "severity": "error"
    },
    {
      "path": "$.invoice.items[0].unit",
      "code": "UNKNOWN_UNIT_CODE",
      "message": "Unit 'STK' unknown. Use UN/ECE codes (e.g., 'C62' for piece)",
      "severity": "error"
    }
  ]
}

Validation Error Codes

Code	Description
`REQUIRED_FIELD`	A required field is missing
`INVALID_VALUE`	Value is out of valid range
`INVALID_DATE_FORMAT`	Date must be YYYY-MM-DD
`INVALID_VAT_FORMAT`	VAT ID format is incorrect
`INVALID_TEMPLATE`	Unknown template name
`UNKNOWN_UNIT_CODE`	Unit code not in UN/ECE list

Handling Errors

Best practices for error handling:

Check the status code before parsing the response body
Parse the details array for specific validation issues
Use the path to identify which field caused the error
Display user-friendly messages from the message field

Example Error Handling (JavaScript)

const response = await fetch('https://api.envoice.dev/v1/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey
  },
  body: JSON.stringify(invoiceData)
});

if (!response.ok) {
  const error = await response.json();

  if (response.status === 422) {
    // Validation errors
    error.details.forEach(detail => {
      console.error(`${detail.path}: ${detail.message}`);
    });
  } else if (response.status === 401) {
    // Invalid API key
    console.error('Invalid API key');
  } else if (response.status === 402) {
    // Quota exceeded
    console.error('Monthly quota exceeded');
  }

  throw new Error(error.error);
}

const result = await response.json();