Error Handling

All Debitura APIs return structured error responses with consistent formats. Across the Customer, Collection Partner, and Referral Partner APIs, error responses centre on a canonical businessErrors[] array. Most endpoints also populate legacy top-level error/message fields for backward compatibility (dual-write); unhandled server errors (500) return businessErrors[] only. Always read businessErrors[] for forward-compatible error handling.

Quick Reference

Status	Meaning	Retryable
400	Validation failed	No — fix request
401	Invalid or missing API key	No — check credentials
404	Resource not found	No — verify ID
422	Business rule violation	No — see solutionUrl
500	Server error	Yes — exponential backoff

API-specific: 409 (Referral Partner conflict), 413/415 (Customer API file uploads).

Business Errors

The businessErrors[] array is returned across all endpoints when a request fails for a reason the API can describe with a typed code — most commonly business-rule violations (422), but also conflicts (409), not-found (404), invalid pagination or file uploads (400/413/415), and unexpected server errors (500). This format is consistent across all Debitura APIs (Customer, Collection Partner, and Referral Partner).

{
  "error": "No collection partner available for this jurisdiction",
  "message": "No collection partner available for this jurisdiction",
  "businessErrors": [
    {
      "type": "NoPartnerAvailable",
      "message": "No collection partner available for this jurisdiction",
      "solutionUrl": "https://support.debitura.com/..."
    }
  ]
}

Field	Description
businessErrors[].type	Error code (see table below)
businessErrors[].message	Human-readable description
businessErrors[].solutionUrl	Link to resolution guidance (when available)
error	Legacy label — a free-form string, usually the human message (occasionally a distinct label such as MissingUserIdentifier). Do not assume it equals businessErrors[0].type; read businessErrors[].type for the canonical code
message	Legacy human-readable description (kept for backward compatibility)

Error messages are safe to display, not to parse

Across all Debitura APIs, message (and businessErrors[].message) is deliberately generic, human-readable text. For unexpected and internal failures it never contains raw exception text, stack traces, or upstream provider/integration error bodies — those details are logged server-side only. Branch your integration logic on businessErrors[].type and the HTTP status code, never on the contents of the message string.

Error Types

Type	Description	Resolution	solutionUrl
NoPartnerAvailable	No collection partner covers the debtor's jurisdiction	Check supported countries or contact support	—
CreditorBlocked	Creditor account is blocked	Contact support	—
MissingDebtCollectionContract	Debt collection contract not signed	Complete contract signing via URL	✓
MissingPowerOfAttorney	Power of attorney not in place	Complete PoA process via URL	✓
MissingKycVerification	Director identity verification required by collection partner	Complete KYC form via URL	✓
CaseNotFound / PaymentNotFound / WebhookNotFound / DivisionNotFound / NotFound	The requested resource was not found or is not accessible — the type is usually resource-specific, with generic NotFound used for some sub-resources	Verify the ID and your access scope	—
InvalidPagination	The page or pageSize parameters are out of range	Adjust pagination parameters — see Pagination	—
IdempotencyConflict	The Idempotency-Key was reused with a different request body (returned as 422; in-flight retries instead get a 409 — see Idempotency)	Use a new key, or replay the original request unchanged	—
Conflict	The request conflicts with the current state of the resource	Re-fetch the resource and retry	—
FileTooLarge	The uploaded file exceeds the maximum allowed size	Reduce the file size and retry	—
UnsupportedFileType	The uploaded file has an unsupported type	Use a supported file format	—
WebhookEventsRequired	No event types were supplied when creating a webhook subscription	Include at least one valid event type	—
WebhookInvalidEventTypes	One or more supplied webhook event types are not recognised	Use valid event types — see Webhooks	—
WebhookInvalidUrl	The webhook subscription URL failed validation (e.g. non-HTTPS)	Provide a reachable HTTPS URL	—
InternalError	An unexpected server error occurred	Retry with exponential backoff	—

When solutionUrl is provided, it links directly to the portal page where the user can resolve the issue.

Validation Errors (400)

Returned for field-level validation failures. Keys are field names; values are arrays of error messages.

{
  "amount": ["Amount must be greater than zero"],
  "debtor.email": ["Invalid email format", "Email is required"]
}

Not Found & Server Errors (404/500)

Not-found and unexpected server errors return the same structured envelope as business errors. The not-found type is usually resource-specific — CaseNotFound, PaymentNotFound, WebhookNotFound, DivisionNotFound — with a generic NotFound for some sub-resources; server errors use InternalError. Server errors never leak stack traces or internal details.

{
  "error": "Case with ID 'abc123' not found",
  "message": "Case with ID 'abc123' not found",
  "businessErrors": [
    {
      "type": "CaseNotFound",
      "message": "Case with ID 'abc123' not found",
      "solutionUrl": ""
    }
  ]
}

Problem Details (401)

Authentication errors return RFC 7807 Problem Details with Content-Type: application/problem+json.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.2",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}

Framework-level field validation ([Required], [MinLength], etc.) also returns RFC 7807 ValidationProblemDetails; see the Validation Errors section above for the controller-level validation shape.

Retry Strategy

For 500 errors, use exponential backoff with max 3 retries. See Idempotency for safe retry patterns.