​

validation_error

​

Example response

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body: vat_numbers must contain between 1 and 50 items",
    "docs_url": "https://docs.avatcado.com/errors/validation_error"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

​

What happened?

• vat_numbers array is empty or contains more than 50 items
• vat_numbers is not an array of strings
• Required fields are missing from the request body
• Extra fields with incorrect types were provided

​

How to fix

1. Check the message field: It describes exactly which validation rule failed
2. Review the request body schema: See Batch Validation for the expected shape
3. Ensure correct types: vat_numbers must be an array of strings, cache must be a boolean

# Correct
curl -X POST https://api.avatcado.com/v1/validate/batch \
  -H "Authorization: Bearer avat_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"vat_numbers": ["NL123456789B01", "DE987654321"]}'

# Wrong - empty array
curl -X POST https://api.avatcado.com/v1/validate/batch \
  -H "Authorization: Bearer avat_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"vat_numbers": []}'

​

Common mistakes

• Sending an empty array: vat_numbers must contain at least 1 item
• Exceeding 50 items: Split large batches into multiple requests of 50 or fewer
• Wrong Content-Type: Make sure you set Content-Type: application/json
• Confusing with invalid_vat_format: validation_error is about the request structure; invalid_vat_format is about individual VAT number formats

​

Catching this error with the SDKs

import Avatcado, { ValidationError } from '@avatcado/node';

const avatcado = new Avatcado('avat_live_your_api_key');
const { data, error } = await avatcado.vat.validate({ vatNumber: '...' });

if (error instanceof ValidationError) {
  console.log(error.message);
  console.log(error.details); // Array<{ field, message }> | null
}

from avatcado import Avatcado, ValidationError

avatcado = Avatcado("avat_live_your_api_key")

try:
    result = avatcado.vat.validate("...")
except ValidationError as e:
    print(e.message)
    print(e.details)  # list of dicts or None

​

Related errors

• invalid_vat_format - Individual VAT number format is wrong (not the request body)
• invalid_json - Request body is not valid JSON at all