# Errors and troubleshooting

Percents errors include an HTTP status and an error instance identifier. Record the identifier when escalating an issue.

```json
{
  "code": 401,
  "httpStatusCode": 401,
  "message": "Unauthorized",
  "uuid": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "name": "UnauthorizedError"
}
```

## Common statuses

| 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 configuration |
| `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 |


## Upload troubleshooting

- A successful presign response does not prove that the file bytes were uploaded.
- A successful storage `PUT` does not mean schema validation or transaction processing succeeded.
- A Plaid schema failure is reported with `schemaValidationPassed: false`; no rows from that file are ingested.
- The schema validation webhook does not wait for transaction processing or human review.


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.