# Error Handling and Validation

The KlickTipp API uses HTTP status codes to distinguish between
technical request handling and business-level validation or subscription errors.

This allows integrations to clearly separate transport and authentication issues
from domain-specific subscription and validation failures.

Integrations must always evaluate **both** the HTTP status code and the response body.

## HTTP Status Code Overview

In addition to business-level errors, the API uses standard HTTP status codes
for technical and protocol-related situations.

| HTTP Status | Meaning |
|  --- | --- |
| 200 / 201 | Request processed successfully |
| 400 | Malformed request or invalid request structure |
| 401 | Authentication required or session invalid |
| 403 | Authenticated but not authorized to access the resource |
| 404 | Resource not found |
| 406 | Request processed but rejected due to validation or business rules |
| 500 | Internal server error |


A status code of 406 indicates that the request was syntactically valid
and successfully processed by the API, but rejected due to business rules
or validation constraints.

## Business and Validation Errors

Errors related to subscription logic, contact state, validation rules, and business constraints
are typically returned with **HTTP status code 406**.

In these cases, the request was syntactically valid and processed by the API,
but rejected due to business rules or invalid data.

The response body for HTTP 406 always contains the numeric `error` field.
Additional fields may be present depending on the error type.

The response body contains a numeric error code providing details about the failure.

The response body for HTTP 406 always contains the numeric `error` field.
Additional fields may be present depending on the error type.


```
{
"error": 10,
"code": 5
}
```

| Property | Description |
|  --- | --- |
| error | Primary error category |
| code | Optional subcode providing additional context |


When handling errors, first evaluate the HTTP status code and, for responses with status 406, inspect the `error` field and the optional `code` value to determine the exact cause.

### Field Validation Errors

Field validation errors occur when submitted values do not match the expected field type
or format configured in the KlickTipp account.

**Error 8** is the only error type that returns field-level validation details
instead of a generic error subcode.


```
{
"error": 8,
"field": "LeadValue",
"name": "fieldLeadValue",
"reason": "must be a numeric value",
"field_value": "A"
}
```

| Property | Description |
|  --- | --- |
| field | Display name of the field as shown in the KlickTipp UI. May be empty |
| name | Field key as sent in the request payload |
| reason | Human-readable explanation of the validation failure |
| field_value | Field value as sent in the request payload |


Field validation errors indicate invalid request data and should not be retried until the payload has been corrected.

### Subscription and Contact Error Codes

The following table lists all business-level error codes returned with HTTP status 406.
These errors indicate that the request was technically valid but rejected due to
subscription state, validation rules, or business constraints.

The response body for HTTP 406 always contains the numeric `error` field.
Additional fields may be present depending on the error type.

| HTTP Status | Error | Code | Description |
|  --- | --- | --- | --- |
| 406 | 4 |  | The email address is unsubscribed. Re-subscription is not allowed. |
| 406 | 5 |  | Invalid email address. |
| 406 | 6 |  | Failed to send the confirmation email. |
| 406 | 7 |  | Email address not found or invalid field format, such as an incorrect timestamp. |
| 406 | 8 |  | Invalid value in a custom field. See Field Validation Errors. |
| 406 | 9 |  | Subscription failed. The contact is not subscribed. |
| 406 | 10 |  | Contact update failed. |
| 406 | 10 | 5 | Contact update failed due to an invalid email address. |
| 406 | 10 | 6 | Contact update failed because the confirmation email could not be sent. |
| 406 | 10 | 9 | Contact update failed. The SMS number is already assigned to another contact. SMS numbers must be unique. |
| 406 | 10 | 10 | Contact update failed. The SMS number is unsubscribed and cannot be re-subscribed. |
| 406 | 10 | 11 | Contact update failed due to an invalid phone number. |
| 406 | 10 | 30 | Contact update failed. The email address is blocked and cannot be used for subscriptions. |
| 406 | 12 |  | Internal error. |
| 406 | 30 |  | The email address is blocked and cannot be used for subscriptions. |
| 406 | 31 |  | SmartTags can only be assigned automatically by the system. |
| 406 | 32 |  | Either an email address or an SMS number must be provided. |
| 406 | 401 |  | Contact not found. |
| 406 | 402 |  | Opt-in process not found. |
| 406 | 403 |  | Tag not found. |
| 406 | 507 |  | The email address is already assigned to another contact. |


## Debugging Guidelines

- HTTP status = 406  and error = 8
Validate request payload and field formats
Retry only after correction
- HTTP status = 406  and error = 10 with subcode
Indicates a contact update failure
Retry may be possible depending on the subcode
- HTTP status ≠ 406
Indicates a technical or authentication issue
Handle independently from business logic


## Summary

HTTP status codes indicate whether a request failed due to a technical issue or a business-level constraint.

Business and validation errors are returned with HTTP status 406 and include a numeric error code in the response body.
The `error` field defines the general failure category, while the optional `code` field provides additional context about the exact cause.

Error 8 represents field-level validation failures and returns structured details about the affected field and the reason for rejection. Validation errors must be corrected in the request payload before retrying the request.

## Related Topics

- [Data Field Types and Input Formats](/guides/data-field-types)
- [Listbuilding API Reference](/listbuilding-api)
- [Management API Reference](/management-api)