Source: https://docs.debitura.com/referral-partners/troubleshooting

# Troubleshooting

Common issues and solutions for referral partner integrations.

<a id="starter-integration"></a>

## Starter Integration

| Issue | Cause | Solution |
| --- | --- | --- |
| Request stays `awaiting_onboarding` | The client hasn't finished setting up their account | Open the current `solutionUrl` again. In test, the signing code goes by email to whitelisted domains only; see [Environments and test data](https://docs.debitura.com/referral-partners/getting-started/environments.md#test-data). |
| Request stays `awaiting_approval` | An existing Debitura client hasn't approved the connection | Debitura has emailed them the invitation; you can also open `solutionUrl`. Approvals expire after the configured period (default 7 days). |
| Request is `expired` | The approval was declined or expired | Send a new request to ask again. |
| `submitted`, but the case isn't collecting yet | The case is in verification or another early stage | Follow `caseStatus` and the case webhooks. |
| No `collection_request.updated` event arrived | Delivery is best effort | Read the request with `GET /collection-requests/{id}`. Never create a new request because an event is missing. |
| Retry returns an old step | Same `Idempotency-Key` within 24 hours returns the original response | Read the request for the current state. |

<a id="client-onboarding-full-integration"></a>

## Client Onboarding (Full Integration)

| Issue | Cause | Solution |
| --- | --- | --- |
| `409 ClientExistsNeedsLinking` | Client already exists in Debitura | Present the approval URL to the client. See [Handling 409 Conflicts](https://docs.debitura.com/referral-partners/integration-guides/client-onboarding-conflicts.md). |
| `409 ClientAlreadyLinkedToAnotherPartner` | Client linked to another partner | Contact Debitura support. Only one partner link per client. |
| `500` on `POST /clients` (matched non-creditor) | Matched account is not a creditor (e.g. a collection partner) — a data-integrity anomaly. `InvalidClientType` is defined in the enum but not currently returned as a 409. | Contact Debitura support. See [InvalidClientType](https://docs.debitura.com/referral-partners/integration-guides/client-onboarding-conflicts.md#invalidclienttype). |
| Link request expired | Configured per-partner TTL (default 7 days, max 30) elapsed without approval | Subscribe to `client.link_expired` to detect expiry; call `POST /clients` again with the same `externalTenantId` to generate a fresh approval URL. |
| Onboarding not completing | Client didn't finish flow | Resend the onboarding URL. Check if they received it. |

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

## Authentication

| Issue | Cause | Solution |
| --- | --- | --- |
| `401` on Customer API after successful calls | Bearer token expired (30-min lifetime) | Implement the [retry-on-401 pattern](https://docs.debitura.com/referral-partners/getting-started/authentication.md#token-expiry-handling). A second 401 means the client link is invalid. |
| Token minting returns `404` | No active link for this `externalTenantId` — never created, or archived/withdrawn | Verify the tenant ID and that the link still exists via `GET /clients/{externalTenantId}`. A token is minted even before SDCA is signed, so a 404 means the link is missing, not unsigned. |

See [API keys and authentication](https://docs.debitura.com/referral-partners/getting-started/authentication.md).

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

## Case Creation

| Issue | Cause | Solution |
| --- | --- | --- |
| `422 MissingDebtCollectionContract` | Client hasn't signed SDCA | Present the `solutionUrl` for contract signing, then retry. |
| `422 MissingPowerOfAttorney` | PoA needed for jurisdiction | Present the `solutionUrl` for PoA signing, then retry. |
| `422 MissingKycVerification` | Collection partner requires KYC but creditor hasn't completed director verification | Present the `solutionUrl` for the KYC form, then retry. Not bypassed by `allowPendingContracts`. See [KYC Verification](https://docs.debitura.com/referral-partners/integration-guides/kyc-verification.md). |
| `422` blocked creditor account | Client account blocked. Returns the typed envelope `{"businessErrors":[{"type":"CreditorBlocked","message":"This account has been blocked. Reason: <reason>","solutionUrl":""}]}`. | Contact Debitura support. Check the error message for the reason. |
| `422` jurisdiction not supported | No collection partner covers the jurisdiction. `NoPartnerAvailable` is not currently returned as a typed business error on this endpoint — the response is an untyped `{"BusinessRule": [...]}` dict. | Show "not supported" message. Don't auto-retry. See [unsupported jurisdictions](https://docs.debitura.com/referral-partners/troubleshooting.md#unsupported-jurisdictions). |
| `400 Bad Request` | Invalid field values | Check required fields. See [Create a Case](https://docs.debitura.com/clients/integration-guides/create-a-case.md#required-fields). |

See the [Error Reference](https://docs.debitura.com/referral-partners/error-reference.md) for all errors across both APIs, or [Error Handling](https://docs.debitura.com/developer-concepts/error-handling.md) for the response format.

<a id="unsupported-jurisdictions"></a>

## Unsupported Jurisdictions

When Debitura doesn't have a collection partner for a jurisdiction, case creation returns `422` with the legacy untyped field-error shape — not a `businessErrors` array with a `type` discriminator:

```json
{
  "BusinessRule": [
    "We don't have an exclusive pre‑legal partner in the provided jurisdiction"
  ]
}
```

The message uses a non-breaking hyphen (U+2011) in "pre‑legal" — match on the key and status code, not the text.

**Handling:**

-   Show a clear message: "This jurisdiction is not currently supported"
-   Don't auto-retry—this won't change until coverage is added
-   Optionally provide a fallback (manual review, contact support)

Coverage changes over time. Check the API response as the source of truth.

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

## Webhooks

| Issue | Cause | Solution |
| --- | --- | --- |
| Signature verification failing | Wrong secret or encoding | Use raw request body (not parsed JSON). See [Webhook Security](https://docs.debitura.com/developer-concepts/webhooks.md#signature-verification). |
| Missing events | Webhook disabled | Check subscription status. Webhooks auto-disable after 8 failed deliveries. |
| Duplicate events | At-least-once delivery | Implement idempotency using `event.id`. See [Best Practices](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md#idempotency-with-eventid). |
| Need to test webhook handler | Can't trigger real events easily | Use [Trigger Test Webhooks](https://docs.debitura.com/referral-partners/integration-guides/webhook-testing.md) to fire events on-demand (test environment only). |

<a id="client-management"></a>

## Client Management

| Issue | Solution |
| --- | --- |
| Need to re-test onboarding with same email | Use the [Reset Test Clients](https://docs.debitura.com/referral-partners/getting-started/environments.md#reset-test-clients) endpoints (test environment only) |
| Client has active cases blocking deletion | Close or delete the cases first, then retry |

<a id="contact-support"></a>

## Contact Support

For issues not covered here, contact [partnerships@debitura.com](mailto:partnerships@debitura.com). For non-technical troubleshooting, see the [Integration troubleshooting checklist](https://support.debitura.com/en/articles/13913400-referral-partners-integration-troubleshooting-checklist-non-technical) and [Customer signup/activation issues](https://support.debitura.com/en/articles/13913385-referral-partners-customer-signup-activation-issues) on the support site.
