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.
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" }
}| Field | Use |
|---|---|
uuid | Identify the specific failure when contacting Percents. |
code | Stable error category for programmatic handling. |
httpStatusCode | Associated HTTP status. |
message | Explanation for people to read. Do not parse it. |
name | Name of the error, when provided. |
reasonCode | Error class, when provided. |
details | JSON 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 Status | What to Do |
|---|---|
400 | Fix the payload. Repeating unchanged invalid input will not help. Purchase intake can return an array of failures for individual events. |
401 | Check the token and environment. |
403 | Check your permissions. Do not try another customer's IDs. |
404 | A lookup read found no accessible accepted record. It does not enroll the customer. |
409 | Check 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. |
429 | Honor Retry-After if supplied and back off. |
5xx | Preserve 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.
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.
| Response | When It Applies |
|---|---|
200 | A successful operation that returns a response body, such as a bulk cardholder-group upsert where every row succeeds. |
201 | Accounts were created. Intake and activity responses include lazilyProvisionedAccounts with the new mappings. |
204 | Intake or activity was accepted without creating accounts. There is no response body. |
207 | A batch has both successful and failed items. Read the individual failures or row statuses. |
400 | The 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.