Percents errors include an HTTP status and an error instance identifier. Record the identifier when escalating an issue.
{
"code": 401,
"httpStatusCode": 401,
"message": "Unauthorized",
"uuid": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"name": "UnauthorizedError"
}| Status | Meaning | Action |
|---|---|---|
400 | Malformed auth header, invalid UUID, unsupported query value, or invalid request | Correct the request; do not retry unchanged |
401 | Invalid token or issuer not enabled for the Omni/upload capability | Verify credentials and onboarding configuration |
403 | File uploads are disabled for the issuer | Contact Percents before retrying |
404 | The offer or merchant is not visible to the authenticated issuer | Verify the ID and issuer/channel-network association |
429 | Request rate exceeded | Retry with bounded exponential backoff and jitter |
5xx | Percents or dependency failure | Retry idempotent GET requests with backoff; retain upload state for support |
- A successful presign response does not prove that the file bytes were uploaded.
- A successful storage
PUTdoes not mean schema validation or transaction processing succeeded. - A schema failure is reported in the result webhook with
schemaValidationSuccess: false. - The final webhook can wait for automated and human review. Escalate after three business days, not immediately after upload.
When contacting support, provide the upload filename, environment, approximate upload time, response error uuid if present, and webhook ID if one was received. Never send API or signing tokens.