API Troubleshooting

Integrations fail, and the difference between a good integration and a painful one is how fast you go from symptom to cause. This guide is the field manual: the failures integrators actually hit on this API, what each one means, and what to do, in the order to check them. Every failure arrives in the same shape: a non-2xx status and a body of the form {"error": {"code": "…", "message": "…"}} (Error Codes): so start from the status and the code, never from a guess. The conventions behind the fixes are in Core Concepts.

401: the key is not accepted

Work through these checks in order

1. Check the stored key for corruption before anything else. A single altered character produces exactly the same 401 as a revoked key. The classic cause: the key passed through a document, a chat message, or a copy-paste that changed it on the way. Compare the stored value against the value as issued, character by character, in your secrets manager.
2. Check the header's shape. The key travels as Authorization: Bearer <your-api-key> (Authentication Endpoints). A missing Bearer, stray whitespace, or the key sent under a different header name all read as "no valid key."
3. Then check revocation and rotation. Was the key rotated by a teammate, or revoked after a suspected exposure (Authentication and Authorization)? A rotated-out key fails exactly like a wrong one.
4. Never "fix" a 401 by retrying. It will not start working on the tenth attempt, and a retry loop against a bad key looks like an attack from the other side.

403: valid key, forbidden call

The key works; the call is outside its bounds. The cause is one of three: the resource is not in the key's granted scopes, the operation exceeds the account's access tier (API Access Tiers), or the identifier in the call belongs to a different account, where it does not resolve for you. Fix the request if it is wrong; request the scope if the integration genuinely needs it (support@aapawz.com). Do not probe neighboring resources after a 403: probing is treated as misuse.

404: the resource is not there: for you

Confirm the id came from an API response to your account, spelled whole and unparsed (ids are opaque, Core Concepts). An id from your own system's records, from an example, or from another account's data will not resolve. If the id is right and the resource was recently created by another of your systems, re-read after a short delay once; a persistent 404 with a verified id is a support case with the id, the call, and the timestamp attached.

400: the request is wrong

The error code names the failing class: a missing required field, a malformed value, money sent as a floating-point number instead of a decimal string, a timestamp not in ISO 8601 UTC. Fix the data at its source: in the system that produced the record: not just in the retried request, or the same defect returns on the next sync. Validation failures never heal by retrying unchanged.

409 and idempotency conflicts: your key was reused

You sent an Idempotency-Key (Idempotency Keys) that was already used with a different request body. This is always a bug in the calling system: keys generated per attempt instead of per write, or a key reused across operations. Find it and fix it there. Never respond by generating a fresh key and re-issuing the write: if the original write was applied, the fresh key applies it a second time: the duplicate product, order action, or refund this error exists to prevent. Where you cannot tell whether the original landed, read the resource's current state and reconcile before writing anything.

Empty results that should have rows

Before concluding the data is missing

1. Check the filters. A status filter, a date window in the wrong timezone (all timestamps are UTC), or a pagination cursor mishandled (Pagination and Filtering (Pagination & Filtering)) are the usual causes. Walk the collection once with minimal filters and compare.
2. Check the account. If your organization runs several accounts or locations (Franchise Integrations), confirm the call ran under the account that owns the data: an empty result under the wrong account is correct behavior.
3. Check the scope. Some collections quietly return only what the key's scope covers. If the scope is narrower than you believed, the fix is a scope request, not a code change.

429: you are over the limit

Stop, read the rate-limit headers (Rate Limit Headers), and resume after the stated window with exponential backoff and jitter. Then fix the cause, because steady-state 429s are a design diagnosis: polling where webhooks belong (Webhooks), walking collections where feeds belong (Feeds and Bulk Data), or unbounded reporting pulls (Analytics). Retrying harder into a 429 extends the restriction and is a policy violation.

5xx: the Platform side failed

Retry with backoff, reusing the idempotency key on writes, and record the code, the request, and the timestamp of each occurrence. A 5xx that persists across a reasonable window with correct requests is a support case; bring the recorded trio. Do not compensate for a failing write path by switching to a second, parallel method of achieving the same write: that is how duplicate application happens when the first path recovers.

Webhook deliveries failing

Check in this order

1. Is your endpoint returning 200 quickly? Slow processing before acknowledgement reads as failure and triggers retries; acknowledge first, process asynchronously (Webhooks).
2. Is signature verification rejecting everything? Recompute over the raw bytes received, before any parsing, and confirm your stored signing secret is current: a rotation on either side is the common cause of a sudden total failure.
3. Are duplicates piling up? Delivery is at least once; if the same event produces repeated effects, your processed-event store is not being checked. Idempotency by event id is the receiver's job.
4. Is the endpoint disabled? A persistently failing endpoint is disabled rather than left dropping events. Fix the receiver, then contact support@aapawz.com to re-enable and replay.

Domain symptoms

• An order seems stuck before paid. Payment was never confirmed; do not fulfill it and do not pursue the buyer outside the Platform. Orders that never confirm resolve on the Platform's side (Orders).
• An order is paid but nothing is moving. Check your own intake first: a missed webhook with no reconciliation poll behind it (Orders): then the fulfillment queue in your system (Fulfillment).
• A price on display is not the price you set. Read the price of record back (Pricing Endpoints); if it differs from what you sent, another writer overwrote it: one writer per price is the fix (Pricing). If it matches, you are looking at a promotion adjustment or a stale view.
• Availability shows stock you do not have. Your inventory report is stale or a second system is also reporting. The discipline and the reconciliation are in Inventory.
• A product cannot be found by browsing. It exists but has no category placement, or no current price: the two silent states Catalog warns about. Check both before re-submitting the product.
• Amounts do not reconcile. Recompute in decimal, per currency, from the payment records: not from order totals, which exclude the deductions between charge and payout (Payments).

The general method

1. Reproduce with the narrowest request that shows the failure.
2. Read the exact error: status, code, and message, not a summary of them.
3. Check your side first: key, scope, filters, id provenance, request shape.
4. Check the Platform's published status and the Changelog for a change that matches the timing.
5. Contact support with the key's identity (never the key itself), the exact request, the exact response, and a timestamp.

Most integration failures are credential corruption, over-narrow filters, and idempotency-key mishandling: in that order. Check the common causes first, every time.

Support: support@aapawz.com.