Skip to main content

TypeAlias.ApiErrorCode

type ApiErrorCode = ObjectEnum<typeof ApiErrorCode>;

Stable, versioned error codes carried by RFC 7807 responses (problem-details.ts, field code). The code never changes once shipped; clients map it to a localized message via their own catalog and fall back to the English detail when unknown. Only errors that can reach a browser UI (admin, dpp consumer) carry a code — backend-only failures (5xx, device callbacks) leave it undefined.

Codes are grouped by domain. Groups added for the email/error i18n effort (#4222):

  • QUOTA_*: organization quota limits and restrictions.
    • QUOTA_{APPLICATION,DPP,WALLET,AGENT_WALLET}_LIMIT_REACHED (429): the monthly/total quota for that subject is exhausted — the admin must raise the plan limit.
    • QUOTA_FEATURE_RESTRICTED / QUOTA_NETWORK_RESTRICTED (403): the requested feature or blockchain network is not enabled for the organization's plan.
  • BILLING_CHARGEBEE_ITEM_NOT_FOUND (422): the resolved Chargebee item_price has no linked item_id (misconfigured catalog); surfaced during onboarding/plan sync.
  • LOYALTY_CAMPAIGN_NOT_RESUMABLE (409): a resume was attempted on a campaign that is not stuck in sending (wrong status, or its send job is still in progress) — only a stranded sending campaign (failed/absent job) can resume.
  • LOYALTY_CAMPAIGN_NOT_SCHEDULABLE (409): a schedule was attempted on a campaign that is not a draft — only a draft can be scheduled for a future send.
  • LOYALTY_CAMPAIGN_NOT_CANCELLABLE (409): a schedule cancellation was attempted on a campaign that is not scheduled — only a scheduled send can be cancelled back to draft.
  • WEBHOOK_*: outbound webhook endpoint management.
    • WEBHOOK_ENDPOINT_NOT_FOUND (404): the endpoint id does not exist for the caller's organization.
    • WEBHOOK_URL_INVALID (400): the target URL is not a valid absolute HTTPS URL.
    • WEBHOOK_URL_BLOCKED (400): the URL resolves to a private, loopback, link-local or cloud-metadata address and is refused (SSRF protection).
  • AGENT_WALLET_EXPENSE_EXPORT_TOO_LARGE (400): the CSV export date range + filters match more transactions than the export cap — narrow the range.
  • DPP_STRUCTURE_JOB_NOT_FOUND (404): the structuration job id does not exist (or its progress stream was requested after the underlying queue job expired).
  • DPP_CHARACTERISTIC_REVIEW_NOT_FOUND (404): the characteristic has no AI extraction to review on this passport (already reviewed elsewhere, or source data).
  • DPP_CHARACTERISTIC_CONFLICT_NOT_APPROVABLE (409): a conflict extraction cannot be approved — the existing value always stays; edit the passport manually or reject the extraction instead.