Error Handling

All Debitura APIs return structured error responses with consistent formats.

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 (422)

Returned when a request violates business rules. This format is consistent across all Debitura APIs (Customer, Collection Partner, and Referral Partner).

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

Field	Description
`type`	Error code (see table below)
`message`	Human-readable description
`solutionUrl`	Link to resolution guidance (when available)

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	✓

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"]
}

Problem Details (401/404/500)

RFC 7807 Problem Details for authentication errors, not-found responses, and server errors.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "Case with ID 'abc123' not found",
  "instance": "/v1/cases/abc123"
}

Response includes Content-Type: application/problem+json.

Retry Strategy

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

Quick Reference​

Business Errors (422)​

Error Types​

Validation Errors (400)​

Problem Details (401/404/500)​

Retry Strategy​