{"templateId":"markdown","versions":[{"version":"1.0","label":"v1.0","link":"/omni-api/overview/errors","default":true,"active":true,"folderId":"6bec560c"}],"sharedDataIds":{"sidebar":"sidebar-omni-api/@1.0/overview/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Errors and troubleshooting","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"errors-and-troubleshooting","__idx":0},"children":["Errors and troubleshooting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Percents errors include an HTTP status and an error instance identifier. Record the identifier when escalating an issue."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": 401,\n  \"httpStatusCode\": 401,\n  \"message\": \"Unauthorized\",\n  \"uuid\": \"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\n  \"name\": \"UnauthorizedError\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-statuses","__idx":1},"children":["Common statuses"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Malformed auth header, invalid UUID, unsupported query value, or invalid request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Correct the request; do not retry unchanged"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid token or issuer not enabled for the Omni/upload capability"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify credentials and onboarding configuration"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["File uploads are disabled for the issuer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contact Percents before retrying"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The offer or merchant is not visible to the authenticated issuer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify the ID and issuer configuration"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request rate exceeded"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry with bounded exponential backoff and jitter"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Percents or dependency failure"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry idempotent GET requests with backoff; retain upload state for support"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"upload-troubleshooting","__idx":2},"children":["Upload troubleshooting"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A successful presign response does not prove that the file bytes were uploaded."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A successful storage ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}," does not mean schema validation or transaction processing succeeded."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A Plaid schema failure is reported with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schemaValidationPassed: false"]},"; no rows from that file are ingested."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The schema validation webhook does not wait for transaction processing or human review."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When contacting support, provide the upload filename, environment, approximate upload time, response error ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uuid"]}," if present, and webhook ID if one was received. Never send API or signing tokens."]}]},"headings":[{"value":"Errors and troubleshooting","id":"errors-and-troubleshooting","depth":1},{"value":"Common statuses","id":"common-statuses","depth":2},{"value":"Upload troubleshooting","id":"upload-troubleshooting","depth":2}],"frontmatter":{"seo":{"title":"Errors and troubleshooting"}},"lastModified":"2026-08-11T02:18:13.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/omni-api/overview/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}