Troubleshooting

Common issues and solutions for referral partner integrations.

Client Onboarding

Issue	Cause	Solution
409 ClientExistsNeedsLinking	Client already exists in Debitura	Present the approval URL to the client. See Handling 409 Conflicts.
409 ClientAlreadyLinkedToAnotherPartner	Client linked to another partner	Contact Debitura support. Only one partner link per client.
409 InvalidClientType	Matched account is not a creditor (e.g. a collection partner)	Contact Debitura support. See Handling 409 Conflicts.
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.

Authentication

Issue	Cause	Solution
401 on Customer API after successful calls	Bearer token expired (30-min lifetime)	Implement the retry-on-401 pattern. A second 401 means the client link is invalid.
Token minting returns 404	Client hasn't completed SDCA signing	Check onboardingDone via GET /clients/{externalTenantId} before minting.

See Authentication for the two-layer auth model.

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.
422 CreditorBlocked	Client account blocked	Contact Debitura support. Check the error message for the reason.
422 NoPartnerAvailable	Jurisdiction not supported	Show "not supported" message. Don't auto-retry. See unsupported jurisdictions.
400 Bad Request	Invalid field values	Check required fields. See Create a Case.

See the Error Reference for all errors across both APIs, or Error Handling for the response format.

Unsupported Jurisdictions

When Debitura doesn't have a collection partner for a jurisdiction, case creation returns 422:

{
  "businessErrors": [
    {
      "type": "NoPartnerAvailable",
      "message": "We don't have an exclusive pre-legal partner in the provided jurisdiction"
    }
  ]
}

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.

Webhooks

Issue	Cause	Solution
Signature verification failing	Wrong secret or encoding	Use raw request body (not parsed JSON). See Webhook Security.
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.
Need to test webhook handler	Can't trigger real events easily	Use Trigger Test Webhooks to fire events on-demand (test environment only).

Client Management

Issue	Solution
Need to re-test onboarding with same email	Use the Reset Test Clients endpoints (test environment only)
Client has active cases blocking deletion	Close or delete the cases first, then retry

Contact Support

For issues not covered here, contact partnerships@debitura.com. For non-technical troubleshooting, see the Integration troubleshooting checklist and Customer signup/activation issues on the support site.