Integration Summary

# 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


## What To Do After an Error

The response status already tells you whether you should correct something, check access, or simply try again later.

### Action Types

Use these four action types to decide what should happen after an error:

- `retry` - try the same request again later because the problem may be temporary.
- `do not retry` - do not send the same request again until something has been corrected.
- `manual review` - the customer, account owner, or person managing the KlickTipp setup should check the situation and decide what to do next.
- `discard` - stop processing because sending the same request again would not be useful.


### Retry Matrix

| Error type | Action | Backoff | Max attempts | Terminal state |
|  --- | --- | --- | --- | --- |
| Local timeout / connection problem | `retry` | short, increasing delay | `3` to `5` | `Dead Letter` |
| `400` | `do not retry` | none | `0` | `discard` |
| `401` | `retry once` | after logging in again | `1` | `Manual Review` |
| `403` | `do not retry` | none | `0` | `Manual Review` |
| `404` | `do not retry` | none | `0` | `Manual Review` |
| `406` | usually `do not retry` | none | `0` | `discard` or `Manual Review` |
| `500` | `retry` | short, increasing delay | `3` to `5` | `Dead Letter` |


### How to Read the Matrix

- Local timeout / connection problem
The request did not reach KlickTipp successfully, or the response did not reach you.
Try again later. If the problem continues, check your network connection or system setup.
- `400`
The request format is wrong.
Correct the request before trying again.
- `401`
Login or session is invalid.
Log in again and retry once.
- `403`
Access is not allowed.
Check permissions, account roles, or whether the action is allowed.
- `404`
The requested resource was not found.
Check the endpoint, ID, or referenced object.
- `406`
The request was understood, but rejected because of business rules or validation.
Check the error code in the response body and correct the underlying issue.
- `500`
An internal server error occurred.
Wait a little and try again later.


### Retry Guidance

Not every error should be retried.

- `400` should not be retried until the request structure has been corrected.
- `401` may be retried once after logging in again or refreshing the session.
- `403` should not be retried unchanged. First check whether the account has permission to perform the action.
- `404` should not be retried unchanged. First verify the endpoint, contact, tag, or opt-in process ID.
- `406` usually should not be retried until the business or validation problem has been corrected.
- `500` may be retried later because it indicates a server-side problem.


For temporary problems, a simple retry policy is usually enough:

- retry once after a short wait
- if the problem still looks temporary, retry a few more times with longer pauses in between
- stop after a reasonable maximum number of attempts, such as `3` to `5`


This kind of gradual waiting is often called **backoff**.
It means you do not retry immediately every time, but wait a little longer after each failure.

Example:

- first retry after about `5 seconds`
- second retry after about `30 seconds`
- third retry after about `2 minutes`


If the request still fails after the chosen maximum number of attempts, stop automatic retries.
At that point, either review the problem manually or move the failed request into a dead-letter state so it can be checked later.

### Special Notes for HTTP 406

Most `406` responses mean the request itself needs attention.

Always inspect the `error` field and, if present, the `code` field before deciding what to do next.

For full request shapes and field examples, see the [Management API Reference](/management-api).

### 406 Business-Code Recovery Matrix

The following matrices group the documented `406` business codes into practical recovery categories.

#### Data-Quality Problems

These errors usually mean the submitted data is wrong, incomplete, or already in conflict with existing data.

| 406 code | Cause | Retry | Manual review rule | Example scenario |
|  --- | --- | --- | --- | --- |
| `5` | Invalid email address | `do not retry` | Review the submitted email address and correct it | A request is sent with an invalid email format |
| `7` | Email address not found, or a field value such as a timestamp is in the wrong format | `do not retry` | Review the email address and field formats | A request uses an incorrect timestamp or a missing email address |
| `8` | Invalid value in a custom field | `do not retry` | Review the field value and field type before sending again | A request sends a text value into a field that only accepts numbers |
| `10` with `code = 5` | Contact update failed because the email address is invalid | `do not retry` | Review the updated email address and correct it | A contact update includes an invalid email address |
| `10` with `code = 9` | Contact update failed because the SMS number is already assigned to another contact | `do not retry` | Review whether the correct SMS number was used | A contact update tries to assign an SMS number that already exists elsewhere |
| `10` with `code = 10` | Contact update failed because the SMS number is unsubscribed and cannot be re-subscribed | `do not retry` | Review whether a different number should be used | A contact update tries to reactivate an unsubscribed SMS number |
| `10` with `code = 11` | Contact update failed because the phone number is invalid | `do not retry` | Review the phone number format before sending again | A contact update includes an invalid phone number |
| `30` | Email address is blocked and cannot be used for subscriptions | `do not retry` | Review whether a different email address should be used | A subscription request uses a blocked email address |
| `32` | Neither email address nor SMS number was provided | `do not retry` | Review whether the required contact data is missing | A request is sent without email and without SMS number |
| `507` | Email address is already assigned to another contact | `do not retry` | Review whether the correct existing contact should be updated instead | A request tries to create or update a contact with an already used email address |


#### Business-Rule and Contact-State Problems

These errors usually mean the data itself may be valid, but the current contact state or KlickTipp rule does not allow the requested action.

| 406 code | Cause | Retry | Manual review rule | Example scenario |
|  --- | --- | --- | --- | --- |
| `4` | The email address is unsubscribed and cannot be re-subscribed | `do not retry` | Review whether a new opt-in path or different contact address is needed | A request tries to subscribe an address that was already unsubscribed |
| `9` | Subscription failed because the contact is not subscribed | `do not retry` | Review whether the correct contact or process was used | A follow-up action expects a subscribed contact, but the contact is not subscribed |
| `10` | Contact update failed for a business-related reason | usually `do not retry` | Review the contact data and any related subcode if available | A contact update fails without a more specific retryable condition |
| `10` with `code = 30` | Contact update failed because the email address is blocked | `do not retry` | Review whether a different email address should be used | A contact update tries to change the address to a blocked email |
| `31` | SmartTags can only be assigned automatically by the system | `do not retry` | Review whether a regular tag should be used instead | A request tries to assign a SmartTag manually |


#### Provider and Delivery Problems

These errors usually mean the request itself may be valid, but delivery or internal processing could not be completed.

| 406 code | Cause | Retry | Manual review rule | Example scenario |
|  --- | --- | --- | --- | --- |
| `6` | Confirmation email could not be sent | `retry later` | Review manually if the problem repeats | A valid subscription request fails because the confirmation email could not be delivered |
| `10` with `code = 6` | Contact update failed because the confirmation email could not be sent | `retry later` | Review manually if the problem repeats | A contact update requires a confirmation email, but it could not be sent |
| `12` | Internal error during processing | `retry later` | Review manually if repeated retries still fail | A technically valid request returns an internal business-processing error |


#### Configuration and Reference Problems

These errors usually mean the request refers to an object that does not exist or is not available in the current setup.

| 406 code | Cause | Retry | Manual review rule | Example scenario |
|  --- | --- | --- | --- | --- |
| `401` | Contact not found | `do not retry` | Review whether the correct contact ID or key was used | A request refers to a contact that does not exist |
| `402` | Opt-in process not found | `do not retry` | Review whether the correct opt-in process ID was used | A request refers to a missing or incorrect opt-in process |
| `403` | Tag not found | `do not retry` | Review whether the correct tag ID was used | A request refers to a tag that does not exist |


### Terminal States

These labels are useful if you document or track what happened after repeated failures.

#### Manual Review

`Manual Review` means the customer, account owner, or person managing the KlickTipp setup should look at the failed request before anything else happens.

Typical examples:

- login keeps failing with `401`
- access is denied with `403`
- a contact, tag, or opt-in process cannot be found
- it is unclear whether the problem is in the data, the account, or the setup


#### Dead Letter

`Dead Letter` means a request was not completed automatically and has been moved aside after all retry attempts were used.

In plain language, this means:

- the system stopped retrying
- the failed request should be checked later
- the request was not silently lost


This is most useful for repeated temporary failures such as `500` errors or connection problems that never recovered.

#### Discard

`Discard` means the request should not be processed again because repeating it would not help.

Typical examples:

- the request format is wrong and the same invalid request keeps being sent
- the data is unusable and there is nothing meaningful to retry
- the request was rejected by business rules and must first be corrected by the user


### Simple Rule of Thumb

- If the problem is in the request data, correct it first.
- If the problem is authentication or access, check login and permissions first.
- If the problem is a server-side failure such as `500`, wait and try again later.
- If the response is `406`, always inspect the `error` field in the response body before deciding what to do next.


## Summary

KlickTipp uses HTTP status codes together with structured response bodies to show whether a request failed because of a technical problem, an authentication or access issue, or a business or validation rule.

Responses with HTTP `406` require special attention because the request was technically valid but rejected for a business or validation reason. In these cases, always inspect the `error` field and, if present, the `code` field to understand the exact cause. Field validation errors such as `error = 8` must be corrected before the request is sent again.

For other failures, the status code helps you decide what to do next: correct the request, log in again, check permissions or IDs, or try again later. Temporary failures such as `500` errors or local connection problems can usually be retried a limited number of times with short pauses in between. Problems that cannot be solved automatically should move to manual review or, after repeated failed retries, to a dead-letter state for later inspection.

## Related Topics

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