Skip to main content

Referral Partners: Integration troubleshooting checklist (non-technical)

This checklist helps you triage common integration issues without writing code. Work through each section to identify the problem, then use the escalation checklist at the end if you need further help from Debitura Support or your developer.

1. Wrong environment (test vs. production)

Problem

API calls succeed but data does not appear in the live platform, or you see test data where you expect real data.

Likely cause

Your integration is pointing at the wrong base URL. Debitura provides two separate environments for the Referral Partner API:

Each environment has its own API keys. A production key will not work against the test endpoint and vice versa.

Fix

  1. Ask your developer which base URL is configured in your integration.

  2. Confirm the API key matches the environment. Production and test keys are issued separately.

  3. If you are unsure which keys you have, see How to request credentials, environments, and support access.

2. Missing or invalid API credentials

Problem

API calls return authentication errors (HTTP 401 or 403), or the integration cannot connect at all.

Likely cause

The Referral Partner API requires an API key in the XApiKey header of every request. Common issues:

  • The API key was never configured in your integration.

  • The key is for the wrong environment (see section 1 above).

  • The key contains extra whitespace or formatting characters.

  • The header name is misspelled. It is XApiKey, written as one word with no hyphens or dashes; a header called X-Api-Key is a different header and the API does not read it.

Fix

  1. Ask your developer to confirm that the XApiKey header is included in every API request, spelled exactly that way.

  2. Verify the key matches the target environment.

  3. To test that the key is valid, your developer can call GET /me. A successful response confirms the key works and returns your partner account details.

  4. If you need a new key or are unsure whether one was issued, contact [email protected].

3. Webhook endpoint not receiving events

Problem

Your system is not receiving webhook notifications (for example, client onboarding events or case updates).

Likely cause

Debitura's webhook system requires specific endpoint configuration. Common issues:

  • No webhook subscription has been created.

  • The endpoint URL uses HTTP instead of HTTPS (HTTPS is required).

  • The endpoint is on a private IP address or localhost (public IP only).

  • The TLS certificate on the endpoint is invalid or expired.

  • The endpoint is not responding with a 2xx status code.

  • The webhook subscription exists but does not include the relevant event types.

Fix

  1. Ask your developer to list current webhook subscriptions by calling GET https://referral-api.debitura.com/v1/Webhooks with your API key.

  2. If no subscription exists, your developer needs to create one by calling POST https://referral-api.debitura.com/v1/Webhooks with the endpoint URL and desired event types.

  3. Confirm the endpoint URL starts with https:// and resolves to a public IP address.

  4. Ask your developer to check that the endpoint responds with a 2xx status code when it receives a POST request.

  5. Review which event types are subscribed. Available referral partner events are: client.onboarding.poa_signed, client.onboarding.contract_signed, client.linked, client.link_declined, client.link_requested, client.link_expired, case.created, case.updated, case.closed, cases.replay_failed, and, for the Starter Integration, collection_request.updated (a collection request's status or invoice outcome changed). For details on what each event means, see Webhook events (business meaning).

  6. With the Starter Integration, if an update seems to be missing, ask your developer to read the collection request again. The current request is always the source of truth: webhook delivery is best effort, and the same event can arrive more than once.

4. Client creation returns a 409 Conflict

Problem

Your integration tries to create or link a client (POST /clients) but receives a 409 Conflict response instead of 201 or 202.

This section covers the Full Integration's client creation call (POST /clients). The Starter Integration handles an existing client differently: Debitura emails one approval invitation to the user you submitted, and the collection request shows the approval step as its next action, with the approval link as the request's link.

Likely cause

A 409 Conflict means the request cannot be completed as sent. Four of the five conflicts identify themselves in a top-level Type field; the fifth does not, so read both places.

In the top-level Type field:

  • ClientExistsNeedsLinking: A user email or the support email you submitted exactly matches an existing Debitura account, and the customer must approve linking to your platform. The response carries an approval URL in data.onboardingLinks.url. After signing in, the customer chooses an eligible existing company to link or creates a new company.

  • ClientAlreadyLinkedToAnotherPartner: The customer is linked to a different referral partner. Only one referral partner link per client is supported.

  • UserCreationFailed: Debitura could not create the user account for this client.

  • PartnerNotAcceptingReferrals: Your referral account is paused or closed to new referrals, so every new client request is refused. No client, user or link is created.

In businessErrors[0].type, not the top-level Type field:

  • IdempotencyKeyInProgress: An earlier POST /clients call sent with the same Idempotency-Key is still being processed. The response carries a Retry-After: 2 header. This one is transient - wait and retry, or let the first request finish. Do not change the payload and reuse the same key; that returns a 422 IdempotencyConflict.

There is no InvalidClientType 409. The value exists in the API's conflict enum but the client-creation handler never returns it: if the existence check reports a match with no creditor behind it, the request fails with a 500 instead. If you have branched on that string, it is dead code - and a 500 here is a defect to report, not a signal to tell the customer to open a second account.

The old AlreadyLinkedDifferentTenant conflict no longer occurs. If the matched account is already linked to your partner account under a different ExternalTenantId, the email match skips it and a new client is created instead.

Fix

  1. Check the Type field in the 409 response body to identify the specific scenario.

  2. For ClientExistsNeedsLinking: Send the approval URL from the response (data.onboardingLinks.url) to the client by redirect, an in-app prompt or your own email - Debitura does not email it. The client must approve the link. For help with this flow, see Customer signup / activation issues.

  3. For IdempotencyKeyInProgress (read it from businessErrors, not Type): wait for the Retry-After interval - currently 2 seconds - then retry with the same key and the same payload.

  4. For ClientAlreadyLinkedToAnotherPartner or UserCreationFailed: Contact Debitura Support at [email protected] to discuss options.

  5. For PartnerNotAcceptingReferrals: Contact Debitura Support at [email protected]. Changing the client's email or creating the client under another identity will not get around it: while your account is paused or closed, every new client request is refused. Clients already linked to you, and their case submissions, are not closed by this account state. A paused account can be resumed; a closed account cannot be reopened. After your account is resumed, your integration can retry the same request with the same Idempotency-Key.

5. Client stuck in "OnboardingRequired" status

Problem

A client was created successfully (202 Accepted) but has not completed onboarding. Calling POST /clients again still returns 202.

Likely cause

The client has not signed the Standard Debt Collection Agreement (SDCA). Until the SDCA is signed, the client cannot submit cases. A 202 response always includes an onboarding URL (onboardingLinks.url) that the client must visit to complete signing. Calling POST /clients again for the same ExternalTenantId returns this current onboarding state; it does not update the existing user's details or create cases included in the repeated request. Submit later cases through the Customer API.

Fix

  1. Resend the onboarding URL (onboardingLinks.url) to the client and ask them to complete the signing process.

  2. If you have webhooks configured, check whether you received a client.onboarding.contract_signed event. If not, the client has not finished onboarding.

  3. Alternatively, your developer can check SDCA status by calling GET /contracts/debt-collection/status with the client's bearer token.

6. Case creation fails with validation errors

Problem

Submitting cases returns HTTP 400 with validation error details.

Likely cause

Required fields are missing or contain invalid data. The API returns a structured error with field-specific messages. Common validation issues include missing debtor email, invalid currency code, negative amounts, or a due date before the invoice date.

Fix

  1. Check the error response body. It contains a Details object with field-specific validation messages.

  2. Forward the error response to your developer so they can fix the data mapping.

  3. Note: validation errors (HTTP 400) abort the entire operation. The client is not created if validation fails.

7. Cases fail with "NoPartnerAvailable"

Problem

Client creation succeeds (201 or 202) but some or all cases appear in the FailedCases array with ErrorType: NoPartnerAvailable.

Likely cause

Debitura does not yet have a collection partner in the debtor's country. The client account is still created and linked, but the case itself is not created for that jurisdiction.

Fix

  1. This is not a bug. Coverage depends on Debitura's collection partner network.

  2. The client is still linked to your account with attribution. If the client creates cases in supported countries later, you earn referral fees.

  3. Check the FailedCases array for the specific countries that are not supported.

  4. If coverage for a particular country is important to you, contact Debitura Support to ask about expansion plans.

8. Webhook signature verification failing

Problem

Your endpoint receives webhook deliveries but signature verification fails, so your system rejects them.

Likely cause

Debitura signs every webhook delivery using HMAC-SHA256. The signing secret is shown only once when the webhook subscription is created. Common issues:

  • The signing secret was not stored or was stored incorrectly.

  • The secret is not being decoded from Base64 before computing the signature.

  • The timestamp tolerance check is too strict (Debitura allows a 5-minute window).

Fix

  1. If the signing secret was lost, your developer can regenerate it by updating the webhook subscription (set RegenerateSecret to true in the update request).

  2. Verify the implementation follows these steps: extract timestamp and signature from the X-Debitura-Signature header, construct the signed payload as {timestamp}.{json_body}, decode the secret from Base64, then compute HMAC-SHA256.

  3. Forward these details to your developer along with a sample webhook delivery for debugging.

Escalation checklist

If the steps above do not resolve your issue, use the checklists below to collect the right information before reaching out.

What to send Debitura Support

Email [email protected] with:

  1. Your partner name and Partner ID.

  2. Which environment you are using (production or test).

  3. A description of the issue and which checklist item above you tried.

  4. The HTTP status code and full error response body (with any sensitive data redacted).

  5. The traceId from the error response, if present.

  6. Timestamps of when the issue occurred.

What to forward to your developer

Share these items with your development team for technical debugging:

  1. The base URL currently configured in the integration.

  2. The HTTP method, endpoint path, and request headers (redact the API key value).

  3. The full response body including any ErrorType, ValidationErrors, or traceId fields.

  4. Webhook subscription details: endpoint URL, subscribed event types, whether the signing secret is stored.

  5. Any logs from your system related to the failed request.

Developer Docs: Developers implementing or debugging the integration can find technical details, code examples, and API schemas in Developer Docs: Referral Partners Troubleshooting.

For a broader overview of how the Referral Partner integration works, see API & integration overview.

Related Articles
Did this answer your question?