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, merchant, or file is not visible to the authenticated issuer | Verify the ID and issuer configuration |
409 | Filename already reserved for this issuer, including historical files | Choose a new filename; do not retry with the same name |
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 |
For the mTLS URL, a TLS handshake failure can occur before HTTP status handling when the client certificate is missing, expired, revoked, untrusted, or paired with the wrong private key. Confirm the client certificate and private-key configuration, then see Trusted Server Connection. A 401 still indicates an API-token problem; mTLS does not replace the entity API token.
- 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. - Whole-file validation failure is reported with
validationStatus=failed; no rows from that file are ingested. - A production terminal result reports ingestion completion/failure; sandbox reports
validation_onlyfor successful validation andfailedfor validation failure. - Poll file status to reconcile missing webhooks. Polling does not start processing.
- For processing errors, inspect counts,
errorMetadata, anderrorUuid.
When contacting support, provide the fileId, filename, environment, approximate upload time, API error uuid or file errorUuid if present, and webhook ID. Never send API or signing tokens.