# API errors (401, 403, 429) (/docs/troubleshooting/api-errors)

{/* Generated by scripts/gen-troubleshooting.mts from lib/troubleshoot.ts. Edit those, not this file. */}

**Symptom:** Your server gets 401, 403, 404 or 429 from the merchant API.

## Why this happens [#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 [#walk-through-it]

Answer one question at a time. The first **no** is almost always the cause.

<Diagnose guide="api" />

## Check these in order [#check-these-in-order]

### 1. Is the key sent correctly and still active? [#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](/docs/api-reference/authentication).

### 2. Does the key have the scope this endpoint needs, right now? [#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](/docs/troubleshooting/card-payments-not-working).

### 3. Is the account unrestricted? [#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? [#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? [#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](/docs/get-started/rate-limits).



## Still stuck? [#still-stuck]

Email [support@swopme.co](mailto: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.
