# Troubleshooting

> What to do when a request fails — start with the request_id.

**First, copy the `request_id`.** Every error response has one:

```json
{ "error": { "code": "invalid_api_key", "message": "…", "request_id": "req_1df6dd76-…" } }
```

With the SDK it is `error.requestId`. Include it whenever you contact Devzity support — it lets us find the exact request.

## Common problems

| You see | Usually means | What to do |
| --- | --- | --- |
| `invalid_api_key` (401) | The key is missing, mistyped, revoked, or you're sending a test key to a live setup (or the reverse). | Check `DEVZITY_SECRET_KEY`, and that it is the key you created for this environment. Create or rotate a key under Developers → API keys. |
| `payment_detection_not_ready` (409) | **Live mode only.** The business has no enabled, ready receiving method yet. | Follow [Going live](https://docs.devzity.com/v1/going-live.md). Test mode never needs this. |
| `insufficient_credit` (409) | **Live mode only.** The business's Service Credit can't cover the next fee. | Top up Service Credit in the dashboard. |
| `idempotency_conflict` (409) | The same `Idempotency-Key` was used with a different request body. | Use a new key for a genuinely different payment; reuse a key only for a retry of the same request. |
| `rate_limit_exceeded` (429) | Too many requests for this key. | Wait for the `Retry-After` header. The SDK does this automatically. |
| Webhook returns 400 / signature fails | You verified a re-serialized or already-parsed body, or used the wrong secret (test vs live endpoint). | Verify the **raw** body, and use the signing secret of that exact endpoint. See [Webhooks](https://docs.devzity.com/v1/webhooks.md). |
| `payment.paid` never arrives | Wrong environment endpoint, or your server didn't answer 2xx. | A **Test** payment only reaches a **Test** endpoint. Check the delivery log under Developers → Webhooks. |

The full list is on the [Errors](https://docs.devzity.com/v1/errors.md) page.

## Nothing works and the message isn't helpful

Check, in order: you are using a **test** key against test mode; `DEVZITY_API_URL` is the API base URL you were given; the request has `Authorization: Bearer <key>`; the JSON body is valid. Then send us the `request_id`.