Campaign Claim — Error Reference

This page lists every error response your application can receive when claiming a campaign reward (POST /campaigns/claims) and when reading claim history (GET /campaigns/claims/me, GET /campaigns/claims).

For the general error envelope, categories, and client-handling patterns, see the Error Handling guide — this page only covers what's specific to claiming.

If you're on the PERS SDK rather than calling the REST API directly, claims go through sdk.campaigns.claimCampaign(...) and surface the same error codes wrapped in the SDK's own error classes (SDK Error Handling):

import { PersApiError, AuthenticationError } from "@explorins/pers-sdk/core";

try {
  const claim = await sdk.campaigns.claimCampaign({
    campaignId: "campaign-123",
    businessId: "business-456" // optional business context
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // 401 — redirect to login
  } else if (error instanceof PersApiError) {
    // The SDK passes the full backend structured error through onto the thrown
    // instance — not just status/message: error.code, error.category, error.domain,
    // error.retryable, and error.details all map 1:1 to the tables below.
    console.error("Claim failed:", error.code, error.status, error.category, error.retryable);
  }
}

Note on 409 CAMPAIGN_CLAIM_ALREADY_PROCESSING: this is expected behavior for double-submits (e.g. a user double-tapping "Claim"), not necessarily an error state — debounce the claim button client-side.

Note on completion-threshold campaigns: if a campaign has a claim-count threshold that hasn't been reached yet, a successful claim (200) is returned without a reward transaction — this is expected, not an error. The reward is granted once the threshold is met on a later claim.

There is no GET /campaigns/claims/{id} endpoint — retrieve claims via the list/me endpoints.

For the underlying error envelope, categories, and general client-side handling patterns, see the Error Handling guide.

• PERS Error Handling — response envelope, categories, correlation IDs
• PERS Authentication Guide — the 401 auth errors referenced above
• PERS SDK Introduction — sdk.campaigns.claimCampaign, PersApiError/AuthenticationError
• PERS SDK Reference — full generated API reference