Skip to content
Last updated

Errors and retries

A failed request needs a clear next action: correct the input, check access or retry without creating a duplicate. Use the error fields, HTTP outcomes and batch rules below to choose that action and retain the information Percents needs to investigate.

Error Fields

Errors include an instance identifier. Save it for support:

{
  "uuid": "err_aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "code": 400101,
  "httpStatusCode": 400,
  "message": "Invalid request",
  "reasonCode": "missing_required_field",
  "details": { "field": "cardId" }
}
FieldUse
uuidIdentify the specific failure when contacting Percents.
codeStable error category for programmatic handling.
httpStatusCodeAssociated HTTP status.
messageExplanation for people to read. Do not parse it.
nameName of the error, when provided.
reasonCodeError class, when provided.
detailsJSON metadata surrounding the error, when provided.

Handle missing optional fields. The numeric values in this example are illustrative. Use the codes documented for your operation.

HTTP outcomes

HTTP StatusWhat to Do
400Fix the payload. Repeating unchanged invalid input will not help. Purchase intake can return an array of failures for individual events.
401Check the token and environment.
403Check your permissions. Do not try another customer's IDs.
404A lookup read found no accessible accepted record. It does not enroll the customer.
409Check for conflicting or ambiguous identities, or an idempotency violation such as reusing an event ID or idempotency key with different data. Resolve the conflict before retrying. Do not invent a new ID to conceal it.
429Honor Retry-After if supplied and back off.
5xxPreserve the request and retry temporary failures with the same identifiers. Use lookup after an uncertain outcome.

For a network failure, preserve the request identifiers and use lookup to check the outcome before retrying.

Purchase lookup returns pending, processed or failed. A processed purchase with reward: null did not qualify for a reward. A failed purchase includes an error. Correct invalid input or retry a temporary failure using the same event ID. The purchase lookup guide explains these processing results.

An offer evaluation failure returns an error. Do not replace it with an insufficient-history fallback.

Single and batch acceptance

Purchase intake accepts one object or a batch of 1–32 objects. Response codes and bodies depend on the operation and whether it creates accounts or accepts only part of a batch. Check the endpoint's response schema as well as the HTTP status.

ResponseWhen It Applies
200A successful operation that returns a response body, such as a bulk cardholder-group upsert where every row succeeds.
201Accounts were created. Intake and activity responses include lazilyProvisionedAccounts with the new mappings.
204Intake or activity was accepted without creating accounts. There is no response body.
207A batch has both successful and failed items. Read the individual failures or row statuses.
400The request is invalid. For purchase intake, this also covers a batch where every submitted event fails.

Acceptance does not confirm a qualified reward. Preserve successful items and correct or retry failed items according to their failure reason. See event intake and activity responses for their response bodies.

Use a unique eventId for each activity event across all your cardholders, batches and both activity routes. Retrying the same event must resolve to the same cardholder with identical normalized facts. Reusing its ID for another cardholder or changed facts causes an idempotency conflict, even within the same cardholder group. See activity idempotency.

For bulk cardholder-group upserts, inspect each row's status. Preserve successful rows and retry only failed rows after resolving their error.