Skip to main content
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.
FieldTypeAlways presentDescription
codestringYesStable, machine-readable Paylead error code. Switch your logic on this, never on title.
titlestringYesHuman-readable explanation. The wording may change between versions.
statusintegerYesThe HTTP status code, repeated in the body for convenience.
errorsarray of objectsNoPresent 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.
instancestringNoReference 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": "VALIDATION_ERROR",
  "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"
    }
  ]
}
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.
CodeMeaningWhen you see it
200 OKSuccessRead or update succeeded.
201 CreatedSuccessResource was created (Consumer, payment account, …).
202 AcceptedSuccessRequest accepted for asynchronous processing, e.g. a payout is initiated synchronously but settled later by the PSP.
204 No ContentSuccessDelete or update succeeded; no body.
400 Bad RequestClient errorPayload invalid, missing field, or malformed JSON. The errors array carries the field-level detail.
401 UnauthorizedAuth errorMissing, expired, or invalid credentials/token.
403 ForbiddenAuth errorAuthenticated, but not allowed: wrong scope, Program, or environment.
404 Not FoundClient errorResource ID does not exist.
409 ConflictClient errorResource already exists, or the state transition is illegal.
500 Internal Server ErrorServer errorUnexpected failure inside the API. 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.
CodeMeaningTypical cause
429 Too Many RequestsThrottlingProgram rate limit exceeded. See Rate limits.
502 Bad GatewayServerA gateway or upstream dependency was unavailable. Retry.
504 Gateway TimeoutServerA 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. Handle both.

​
Handling common errors

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.
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.
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.
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.
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.
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 codeRetry?Strategy
4xx (except 429)NoFix the client. Retrying gives the same error.
429YesHonor Retry-After. Exponential backoff with jitter. See Rate limits.
500, 502YesExponential backoff. Cap at 5 attempts.
504Yes, idempotent onlyGET 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.