Status codes & Error responses

The Veille API uses standard HTTP status codes to indicate the success or failure of API requests. This guide outlines what these status codes mean and provides examples of error responses you might encounter.

Status Codes

Code	Status	Description
200	OK	The request was successful and the response contains the requested data.
400	Bad Request	The request was invalid. This may be due to missing required fields, invalid format, or other validation errors.
401	Unauthorized	Authentication failed or was not provided. Check your API key.
500	Internal Server Error	Something went wrong on our server. Please contact support if this persists.

Error Response Format

All error responses follow a consistent format, making it easier to handle errors in your application:

{
    "error": "Error message describing what went wrong",
    "details": {
        // Optional additional information about the error
    }
}

The details object is optional and only included when there's additional context about the error.

Success Response Format

Successful responses typically follow this format:

{
    "field": "value",
    "allowed": true,
    // Additional response fields depending on the endpoint
}

Common Error Responses

Validation Errors

Invalid Email Format

{
    "error": "Invalid email format",
    "details": null
}

Invalid Domain Format

{
    "error": "Invalid domain format", 
    "details": null
}

Invalid IP Format

{
    "error": "Invalid IP format",
    "details": null
}

Input Validation Errors (Zod)

{
    "error": "Failed to validate input: Invalid field",
    "details": {
        "invalidField": "unknown_field",
        "validFields": ["ip_source_address", "user_agent", "is_bogon"],
        "issue": "INVALID_FIELD"
    }
}

API Request Errors

{
    "error": "UserCheck API error: 401",
    "details": null
}

Blocklist Checks

If an email, domain, or IP is blocklisted, you'll receive a 200 response with:

{
    "email": "blocked@example.com",
    "allowed": false,
    "reason": "blocklisted"
}

Or for disposable domains:

{
    "email": "user@disposable.com",
    "allowed": false,
    "reason": "disposable_domain",
    "provider": "tempmail"
}

Rule Matching

When an IP address matches a security rule:

{
    "ip": "192.168.1.1",
    "allowed": false,
    "reason": "rule_triggered",
    "matched_rules": [
        {
            "rule_id": "123e4567-e89b-12d3-a456-426614174000",
            "name": "Block datacenter IPs",
            "action": "block"
        }
    ]
}

Error Handling Tips

Always check the HTTP status code first to determine the category of response
For 400 errors, inspect the error message and details to understand the validation issue
For allowed: false responses (with 200 status), check the reason field to understand why the entity is blocked

Support

If you encounter persistent errors or need help understanding specific error messages, please contact our support with the chat button in the bottom right corner of the page.