Troubleshooting
When something doesn’t work the way you expected, start here. This section covers the most common confusions encountered in the first week of integration — not API errors (those live in Errors & Conventions) but operational gotchas, configuration mismatches, and “is this supposed to work this way?” questions.
Common issues
Symptoms and fixes — “I’m seeing X” → “do Y.” Concrete scenarios with root causes.
General FAQ
Questions developers ask once and then never again — auth, sandbox vs production, multi-merchant, scope.
Technical FAQ
Deeper implementation questions — request shapes, error handling, encryption, and edge cases.
Where this section sits in the docs
| If you’re seeing… | Go to |
|---|---|
| A specific HTTP error or UCP error code | Errors & Conventions |
| A symptom or “this isn’t doing what I expected” | Common issues |
| A conceptual or process question | General FAQ |
| A deeper implementation question | Technical FAQ |
| A platform-specific behavior question | The relevant platform page |
| An open question after reading the above | Firmly |
When to escalate
If you’ve checked the catalog and FAQ, instrumented logs, and still can’t reproduce or resolve, escalate with:
- The full request URL (including query string)
- The full response body
- The
Idempotency-Keyyou used (if any) - The merchant
domainand your_appId - A timestamp (UTC) of when the request was made
- A short narrative of what you expected vs what happened
That set of inputs typically resolves the issue in a single back-and-forth.