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.

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

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.

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
}

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 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"
}

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

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 = 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

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

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.

• 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.

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.

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.

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

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

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

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

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

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

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 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 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

• 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.

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.

• Data Field Types and Input Formats
• Listbuilding API Reference
• Management API Reference