Source: https://docs.debitura.com/clients/troubleshooting

# Troubleshooting

Quick reference for common integration issues.

<a id="authentication"></a>

## Authentication

| Issue | Solution |
| --- | --- |
| `401 Unauthorized` | Check API key is correct and included in `XApiKey` header |
| Key not working | Generate a new key in [Creditor Portal → API Keys](https://app.debitura.com/CreditorApiKey) |

See [Authentication](https://docs.debitura.com/clients/getting-started/authentication.md) for setup details.

<a id="case-creation"></a>

## Case Creation

| Issue | Solution |
| --- | --- |
| `400` validation error | Check required fields — see [Create a Case](https://docs.debitura.com/clients/integration-guides/create-a-case.md#required-fields) |
| `422` business error | Inspect the response shape. Typed `businessErrors[]` entries may include a `solutionUrl` for contract signing; field-keyed validation responses do not. |
| `"Must be unique"` error | Your `creditorReference` already exists — use unique values |

See [Create a Case — Error Handling](https://docs.debitura.com/clients/integration-guides/create-a-case.md#error-handling) for all error types.

<a id="webhooks"></a>

## Webhooks

| Issue | Solution |
| --- | --- |
| Not receiving events | Verify endpoint is HTTPS with valid certificate |
| Signature verification fails | Use raw body (not parsed JSON) and Base64-decode the secret |
| Webhook disabled | Check `disabledReason` and re-enable with `"isActive": true` |

See [Webhooks — Troubleshooting](https://docs.debitura.com/clients/integration-guides/webhooks.md#troubleshooting) for details.

<a id="error-reference"></a>

## Error Reference

For complete error handling across all APIs, see [Error Handling](https://docs.debitura.com/developer-concepts/error-handling.md).