Errors

Paylead uses standard HTTP status codes for protocol-level outcomes and a JSON error envelope for application-level detail. Errors come from two layers:

The application handles most calls and, on failure, returns the structured error envelope below; parse it for the precise cause.
The infrastructure in front of the API (gateway, authentication, throttling) can answer first, and those responses may not carry the envelope.

Always branch on the HTTP status first, then enrich with the envelope when it is present. Why this matters. A 400 from malformed JSON and a 400 from a field that fails validation require different fixes. The envelope’s code and errors disambiguate them.

Error envelope

Errors raised by the application share the same JSON shape: a problem-details-style object (the Paylead error profile). Three fields are always present (code, title, status); errors and instance are added when relevant. Errors raised at the edge may not include it.

Code examples coming soon. The Paylead API (v2) is still under construction. Request and response examples for this section will be published once the contract is finalized. In the meantime, contact your Paylead account manager for early-access details.

Field	Type	Always present	Description
`code`	string	Yes	Stable, machine-readable Paylead error code. Switch your logic on this, never on `title`.
`title`	string	Yes	Human-readable explanation. The wording may change between versions.
`status`	integer	Yes	The HTTP status code, repeated in the body for convenience.
`errors`	array of objects	No	Present on validation failures. Each item describes one problem; its fields are endpoint-specific (offending location, expected format, …). `null` when there are no field-level details.
`instance`	string	No	Reference to this specific occurrence of the failure, when the platform sets one. Include it in support tickets if present. May be `null`.

Example 400 response

{
  "code": "PL-400-00",
  "title": "The request payload is invalid.",
  "status": 400,
  "instance": "req_01J9Z3K8QY",
  "errors": [
    {
      "loc": ["body", "id"],
      "msg": "String should match pattern '^[a-zA-Z0-9_-]+$'",
      "type": "string_pattern_mismatch"
    }
  ]
}

Locating the failing field in nested payloads

errors[].loc appears when the failure traces back to a specific field of the input payload, for example a missing value, a wrong type, or a format mismatch. Most other failures, including business-rule errors such as 409 Conflict, do not carry field-level detail: errors is null in that case. When present, loc is a path from the request body down to the offending field: one segment per level, either an object key or the numeric index of an item inside a list. Read it left to right to walk down to the exact field that failed. Some payloads nest several levels of lists. Creating transactions, for example, sends a list of banks, each holding a list of accounts, each holding a list of transactions. A failure on the type of the first transaction of the first account of the first bank looks like this:

Nested loc example

{
  "loc": ["body", "banks", 0, "accounts", 0, "transactions", 0, "type"],
  "msg": "Not a valid choice.",
  "type": "invalid"
}

Log the full error envelope (code, title, status). When the response carries an instance, include it in any bug report you open; it is the fastest way for Paylead support to find the failure in our logs.

HTTP status codes

Returned by the application

On failure, these carry the error envelope above.

Code	Meaning	When you see it
`200 OK`	Success	Read or update succeeded.
`201 Created`	Success	Resource was created (Consumer, payment account, …).
`202 Accepted`	Success	Request accepted for asynchronous processing, e.g. a payout is initiated synchronously but settled later by the PSP.
`204 No Content`	Success	Delete or update succeeded; no body.
`400 Bad Request`	Client error	Payload invalid, missing field, or malformed JSON. The `errors` array carries the field-level detail.
`401 Unauthorized`	Auth error	Missing, expired, or invalid credentials/token.
`403 Forbidden`	Auth error	Authenticated, but not allowed: wrong scope, Program, or environment.
`404 Not Found`	Client error	Resource ID does not exist.
`409 Conflict`	Client error	Resource already exists, or the state transition is illegal.
`500 Internal Server Error`	Server error	Unexpected failure inside the API. Retry with backoff.
`502 Bad Gateway`	Server error	An upstream dependency (for example the PSP) was unavailable. Retry with backoff.

Raised at the edge

Some requests never reach the application: the API gateway and upstream infrastructure answer first (throttling and gateway failures). These responses may not carry the error envelope: the body can be empty, plain text, or a different JSON shape, so branch on the HTTP status and never assume a parseable code / title.

Code	Meaning	Typical cause
`429 Too Many Requests`	Throttling	Program rate limit exceeded. See Rate limits.
`504 Gateway Timeout`	Server	A gateway or upstream dependency timed out. Retry idempotent calls only.

Authentication is also enforced here: 401 and 403 (listed above) are returned by the application with the envelope, but an edge rejection may arrive without it. 502 behaves the same way: the application returns it with the envelope when an upstream dependency such as the PSP is unavailable, while a gateway can also emit a 502 without one. Handle both.

Paylead error codes

The code field is what you branch on. The codes below are the ones the Perks endpoints return, grouped by the operation that raises them. Each endpoint’s own reference page lists the codes it can return. Match the full code. Two codes sharing an HTTP status carry unrelated causes, and each one maps to its own message on the payout and IBAN flows. Returned by every endpoint

Code	HTTP	Title	When you see it
`PL-400-00`	`400`	Bad Request	Payload or query parameter invalid. Read the `errors` array.
`PL-401-00`	`401`	Unauthorized	Token missing, expired, or invalid.
`PL-404-00`	`404`	Not Found	The `offer_id`, `brand_id`, or `reward_id` does not exist.
`PL-404-02`	`404`	Consumer Not Enrolled	The `consumer_id` is unknown to this Program. Enroll the Consumer first.

Enrollment (POST /perks/consumers)

Code	HTTP	Title	When you see it
`PL-409-09`	`409`	Consumer Not Enrolled On Platform	The Consumer must exist on the platform before being enrolled on Perks.
`PL-409-10`	`409`	Consumer Already Enrolled	The Consumer is already enrolled. Read it instead of recreating it.

Pool and KYC

Code	HTTP	Title	When you see it
`PL-403-01`	`403`	Consumer Pool Not Enabled	The Consumer has no pool. Raised on the payment account, KYC, and payout endpoints.
`PL-409-05`	`409`	Consumer KYC Not Ready	KYC is incomplete or still under review. Blocks IBAN designation and payout.
`PL-400-06`	`400`	KYC Rejected	The PSP rejected the submitted KYC data.

Payment account (/perks/consumers/{consumer_id}/accounts/payment)

Code	HTTP	Title	When you see it
`PL-400-05`	`400`	Payment Account Recipient Rejected	The PSP refused the IBAN, on creation or on deletion.
`PL-400-08`	`400`	Natural User Address Missing	The Consumer has no address, which the PSP requires to register a recipient.
`PL-409-04`	`409`	Payment Account Already Exists	An IBAN is already designated. Delete it before designating another.
`PL-404-05`	`404`	Payment Account Not Found	No IBAN designated for this Consumer.

Payout (POST /perks/consumers/{consumer_id}/pools/me/payouts)

Code	HTTP	Title	When you see it
`PL-409-07`	`409`	Pool Below Threshold	The pool balance is under the payout threshold the Program Manager configured. See Ventilation.
`PL-409-08`	`409`	Payment Account Missing	No IBAN designated. Collect one first.
`PL-409-11`	`409`	Payment Account Not Validated	The designated IBAN is not validated yet.
`PL-409-06`	`409`	Consumer Outflow Blocked	Payouts are blocked for this Consumer.
`PL-400-07`	`400`	Payout Rejected	The PSP refused the transfer.
`PL-409-999`	`409`	Contact Admin User	The payout cannot proceed and needs Paylead intervention.

Segments (/perks/consumers/{consumer_id}/segments/{segment_reference})

Code	HTTP	Title	When you see it
`PL-404-03`	`404`	Segment Not Found	No Segment with that reference in the Program.
`PL-404-04`	`404`	Segment Assignation Not Found	The Consumer is not assigned to that Segment.
`PL-409-03`	`409`	Segment Already Assigned To Consumer	The assignation already exists.

Vouchers (/perks/consumers/{consumer_id}/vouchers, .../vouchers/orders, beta)

Code	HTTP	Title	When you see it
`PL-400-09`	`400`	Voucher Order Invalid	The Offer is unknown or not a Voucher Offer, the selection is empty, or `amount_step` is not respected.
`PL-400-12`	`400`	Voucher Amount Out Of Range	The requested amount falls outside the Offer’s `min_amount` to `max_amount` range.
`PL-409-12`	`409`	Voucher Price Changed	The Offer price moved between display and order. Refresh the Offer and ask the Consumer again. Treat this as a normal outcome.
`PL-409-15`	`409`	No Payin Account Declared	The Consumer has no debit account at all. Route them to declare one. Delegated payment only, like `PL-400-13`.
`PL-400-13`	`400`	Missing Payin Account	The Consumer has debit accounts, but none was selected on the order, or the selected one does not exist. Make them pick one.
`PL-400-10`	`400`	Voucher Payment Rejected	The PSP refused the payment. The order stays payable.
`PL-400-11`	`400`	Voucher Payment Verification Failed	Paylead could not check the pay-in. Retry, otherwise the daily job settles the order.
`PL-404-07`	`404`	Voucher Order Not Found	No order with that `order_id`.
`PL-409-13`	`409`	Voucher Update Forbidden	The Voucher cannot be archived, unarchived, or updated in its current state.

Upstream (any PSP-backed operation)

Code	HTTP	Title	When you see it
`PL-502-03`	`502`	PSP Service Unavailable	The payment provider was unreachable. Retry with backoff.

Handling common errors

400 Bad Request

The payload is malformed JSON, or a field fails validation.Fix. Read the errors array: each entry points at the offending field and the rule it broke. Coerce the value on the client and resend. If errors is empty, the body itself was not valid JSON.

401 Unauthorized

The credentials or bearer token are missing, malformed, or expired.Fix. Verify the Authorization header. For OAuth2, request a fresh token from /tokens (client-credentials flow) and check the API key in Shift. See Authentication.

403 Forbidden

The token is valid but is not allowed to access this resource, for example it was issued for a different Program or environment, or it lacks the required scope (LOYALTIES, PERKS, TX_INJECTION, or ALL).Fix. Confirm you are using the token issued for this Program and this environment (sandbox vs production), and that it carries the scope the endpoint needs. See Authentication.

404 Not Found

No resource matches the given ID, for example no Consumer with that consumer_id.Fix. Verify the ID and confirm the resource was created against the same environment. Create it if needed.

409 Conflict

The resource already exists, or the requested state transition is illegal, for example creating a Consumer whose id is already in your Program.Fix. Read the resource first, then update it instead of recreating it, or pick a new identifier. Never reuse an ID for a different resource.

500 / 502 Server errors

Something failed inside Paylead (500) or in an upstream dependency (502). Not your fault, but you still need to handle it.Fix. Retry idempotent calls with exponential backoff. If the issue persists, share the response body (including the instance when present) with Paylead support.

Retry strategy

Status code	Retry?	Strategy
`4xx` (except `429`)	No	Fix the client. Retrying gives the same error.
`429`	Yes	Honor `Retry-After`. Exponential backoff with jitter. See Rate limits.
`500`, `502`	Yes	Exponential backoff. Cap at 5 attempts.
`504`	Yes, idempotent only	`GET` and `DELETE` are safe to retry. Retrying a timed-out or `POST` may create a duplicate.

Paylead does not support an Idempotency-Key request header. When a POST times out, you cannot ask the server to deduplicate the retry. Mitigate by re-reading the resource via GET before retrying, or by using deterministic identifiers (for example, your own Consumer ID) so a re-creation surfaces as 409 instead of a duplicate.

What’s next

FAQ

Common integration questions, answered.

Security

Data protection and regulatory compliance for your integration.

Support

Contact Paylead support. Share the failing response, including its instance when present.

Introduction

Get started

Consumers

Perks

Loyalty

Reference & help

Security & compliance

Error envelope

Locating the failing field in nested payloads

HTTP status codes

Returned by the application

Raised at the edge

Paylead error codes

Handling common errors

Retry strategy

What’s next

FAQ

Security

Support

​Error envelope

​Locating the failing field in nested payloads

​HTTP status codes

​Returned by the application

​Raised at the edge

​Paylead error codes

​Handling common errors

​Retry strategy

​What’s next

FAQ

Security

Support

Error envelope

Locating the failing field in nested payloads

HTTP status codes

Returned by the application

Raised at the edge

Paylead error codes

Handling common errors

Retry strategy

What’s next