API errors (401, 403, 429)
Your server gets 401, 403, 404 or 429 from the merchant API.
Symptom: Your server gets 401, 403, 404 or 429 from the merchant API.
Why this happens
The merchant API uses standard HTTP status codes, and its error bodies are built to tell you what's wrong. A 403 names the scope you're missing and lists what the key can do right now. Key and scope errors are about your setup, never the buyer's, so log the body on your server and show buyers something neutral.
Walk through it
Answer one question at a time. The first no is almost always the cause.
Is the key sent correctly and still active?
How to check: Send Authorization: Bearer swop_sk_… (or X-API-Key). A 401 means missing, mistyped or revoked.
Check these in order
1. Is the key sent correctly and still active?
How to check: Send Authorization: Bearer swop_sk_… (or X-API-Key). A 401 means missing, mistyped or revoked.
If not: Check the header, and create a new key in Dashboard → Developer if it was revoked. See Authentication.
2. Does the key have the scope this endpoint needs, right now?
How to check: A 403 body lists grantedScopes and effectiveScopes. commerce.card can be granted but not effective until verification completes.
If not: Create a key with the missing scope. For commerce.card, finish merchant verification. See Card payments not working.
3. Is the account unrestricted?
How to check: A 403 with code ACCOUNT_FLAGGED means it isn’t.
If not: Contact support@swopme.co.
4. Does the ID belong to your account?
How to check: Swop answers 404 for things that exist but aren’t yours, so IDs can’t be probed.
If not: Check you’re using the key of the account that owns the product or order.
5. Are you under the rate limits?
How to check: 1,200 requests per 5 minutes per key, 6,000 per IP. A 429 includes retryAfter.
If not: Wait retryAfter seconds and back off. See Rate limits.
Still stuck?
Email support@swopme.co with your swop.id, roughly when it happened, and any order, checkout or request ID. Never send your secret key. You can also use the Ask button on any page.