DutyClaims Docs
Errors & Retries

Treat problem responses as operational signals, not as generic failures.

The partner API publishes structured problem payloads with request IDs and retry hints. This page shows the shared shape, the common failure classes, and the discipline expected from production integrations.

AuthenticationWebhooksAPI Reference

Problem payload shape

{
  "type": "https://api.dutyclaims.com/problems/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The payload did not satisfy the current contract.",
  "requestId": "req_123",
  "correlationId": "corr_456",
  "error": "validation_error",
  "issues": [
    {
      "path": "entries[0].entryNumber",
      "message": "Entry number is required."
    }
  ]
}

Fields to preserve in logs

  • requestId: always capture this before opening a support or ops thread.
  • correlationId: capture it when present to connect platform-side diagnostics.
  • issues: for 422 responses, use field-level issues instead of collapsing the failure into one generic message.
  • retryAfterMinutes: respect this when present instead of inventing your own backoff window.

Problem schema fields

FieldTypeRequired
typestringYes
titlestringYes
statusintegerYes
detailstringYes
requestIdstringYes
correlationIdstringOptional
errorstringYes
issuesarrayOptional
retryAfterMinutesintegerOptional

Request conventions

SignalCurrent ruleWhy it matters
AuthorizationUse `Authorization: Bearer …` as the default credential header for most partner routes.This is the common production-safe path across clients, claims, financing, litigation, reporting, and webhook operations.
X-API-KeyUse `X-API-Key` only on route families that still publish that compatibility path, most notably diligence routes.Do not assume every v1 route accepts the legacy header just because the same tenant has a managed credential.
Idempotency-KeySend the same key when retrying a replay-safe write with the exact same payload. Change the key when the intent changes.This is how create or transition routes avoid duplicated claims, offers, disbursements, notifications, or package deliveries during retries.
X-Correlation-IdSend it when you want your own trace handle preserved end to end.If you omit it, the API falls back to the request ID as the correlation ID, which is still safe but less useful for caller-side tracing.
X-Request-IdOptionally send your own request identifier. If omitted, the API generates one and echoes it back.This is the fastest way to line up client logs, API responses, support escalations, and partner incident notes.

Current paginated list routes

The current list surfaces use the same basic contract: send page and limit, then keep paginating while hasMore remains true.

Unauthorized 401

Credentials are missing, malformed, revoked, or no longer accepted for this route.

Rotate or re-issue the managed credential, then retry with the exact required header semantics.

Open problem guide

Forbidden 403

The authenticated partner lacks the capability, scope, authority state, or environment required for the attempted action.

Check partner capabilities, sandbox versus production state, delegated authority, and any route-specific readiness gates.

Open problem guide

Not Found 404

The requested object or route does not exist for the authenticated partner context.

Verify identifiers, route versioning, and whether the partner org is authorized to read that resource.

Open problem guide

Conflict 409

The request clashes with the current server state, commonly because idempotency or lifecycle transitions are already in progress.

Inspect the prior request or existing object state before retrying.

Open problem guide

Validation Error 422

The payload shape or field semantics do not satisfy the current contract.

Compare the payload against the current v1 schema, required fields, and any documented enum constraints.

Open problem guide

Too Many Requests 429

Rate limiting blocked the request temporarily.

Honor the Retry-After header and use idempotency where supported before retrying.

Open problem guide

Internal Server Error 500

An unexpected server-side failure prevented the route from completing.

Capture the request ID and correlation ID, then escalate with the exact timestamp and route attempted.

Open problem guide

Write-path idempotency

For replay-safe write flows, reuse the same Idempotency-Key only when the intent and payload are identical. Reusing a key for a different payload is a conflict, not a retry.

Retry rules

  • Retry 429 only after the published retry window, not on a fixed loop.
  • Treat 409 as a state conflict and re-read the current object before you submit another write.
  • Treat 401 and 403 as authz configuration problems, not transient network failures.
  • Reuse the same Idempotency-Key only for a real retry of the same payload.

Before you escalate

  1. Capture the exact route, method, timestamp, request ID, and correlation ID.
  2. Confirm whether the issue is sandbox-only, production-only, or capability-gated.
  3. Compare the payload to the current contract instead of relying on stale local examples.
  4. Include the response body, any field-level issues, and the idempotency key when a write was replayed.