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 Client Onboarding.
`409 AlreadyLinkedToAnotherPartner`	Client linked to another partner	Contact Debitura support. Only one partner link per client.
`409 AlreadyLinkedDifferentTenant`	Client already linked with different tenant ID	Use the existing `externalTenantId` for this client.
Link request expired	7-day expiry passed	Call `POST /clients` again to generate a new link request.
Onboarding not completing	Client didn't finish flow	Resend the onboarding URL. Check if they received it.

Issue	Cause	Solution
`401 Unauthorized` on Referral API	Invalid API key	Verify the `XApiKey` header. Keys are environment-specific.
`401 Unauthorized` on Customer API	Expired bearer token	Tokens expire after 30 minutes. Mint a new token.
Wrong environment data	Mixed test/production keys	Ensure you're using matching API keys and base URLs.

See Authentication for the two-layer auth model.

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 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 Error Handling for the full error response format.

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

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

Handling:

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

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

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

For issues not covered here, contact contact@debitura.com.