Skip to main content

Error handling

Read any Paylode error the same way: the HTTP status tells you what kind of problem it is, and the body — when there is one — tells you which rule you hit.

Every Paylode API follows the same conventions, so error handling you write for one integration carries over to the next. This page covers the shared rules; the exact codes each operation can return are listed on that operation's page in the API Reference.

The three body shapes​

  • Business rejections (400) return a plain JSON string naming the rule you hit — for example "PERK_RANK_DUPLICATED" or "IDEMPOTENCY_KEY_CONFLICT". There's no wrapper object; match on the string itself. Each operation's 400 response on the API reference enumerates its possible codes.
  • Refusals with context (403 and 422 on some operations) return an object with a reason code and a human-readable message — for example a Boost reward called from an address outside your IP whitelist (403), or a Boost campaign whose every active reward has run out (422 with reason: "ALL_DEPLETED").
  • Server errors (500) return an object with a message and a requestId. Log the requestId — it's how Paylode finds your exact request when you report a problem.

Authentication failures (401) generally carry no body at all.

What each status means​

StatusMeaningWhat to do
400The request broke a business rule; the body names it.Fix the request — don't retry as-is.
401Missing or invalid API key.Check the X-API-Key header — see Authentication.
402The feature isn't enabled for your account or collection.Talk to your Paylode contact about enabling it.
403Authenticated, but not allowed — wrong owner, or a source restriction (for example an IP whitelist).Check ownership of the id you're addressing and your IP whitelist.
404The id doesn't exist — or doesn't belong to your account.Verify the id; remember every read is scoped to your own data.
409The resource is in a state that refuses the call — a paused Boost campaign serving teasers, a reused idempotency key with a different payload.Read the state first, or resolve the conflict.
422The request is fine, but there's nothing left to give — every active reward in a Boost campaign is depleted (ALL_DEPLETED). A campaign with no active incentives is different: that's a 200 with an empty list.Top up the gift-card pools or swap in fresh perks, then retry.
5xxSomething failed on Paylode's side.Retry with backoff; capture the requestId for support.

There are no published platform-wide rate limits — see Platform basics for the transport ground rules.

Retrying safely​

Most reads are safe to retry. Two important exceptions and one guarantee:

  • Coupon allocation is not idempotent. Every call to allocatePerkCoupon consumes a fresh code from the pool — a blind retry allocates a second code. Cache the code you received instead. See Coupon.
  • Boost rewards are idempotent per journey. Requesting rewards again for the same journey returns the same reward, so retries are safe there.
  • Gift-card orders use an idempotency key you supply, so a retried order can't be double-placed — a reused key with a different payload is rejected with IDEMPOTENCY_KEY_CONFLICT.