Troubleshooting
Common API problems and how to fix them.
The problems people hit most often, and how to resolve them.
Errors by status code
| Symptom | Fix |
|---|---|
401 unauthorized | The header must be exactly Authorization: Bearer m123_…. The key may be revoked — create a new one. |
403 insufficient_scope | You used a sending-only key on a contacts/campaigns/templates endpoint. Use a Full access key. |
403 forbidden on send | Your from domain isn't verified, or it has an open DNS recommendation. Verify it under Domains. |
409 conflict on send | The recipient is suppressed (bounced, complained, or unsubscribed). Remove it from your flow. |
429 — which one? | Check error.code: rate_limit_exceeded = too fast (honor Retry-After); quota_exceeded = plan limit hit. |
502 send_failed | Transient provider error — retry with backoff. If persistent, check the message and sender config. |
Delivery problems
| Symptom | Fix |
|---|---|
| Email "sent" but not received | Check spam, confirm the recipient isn't suppressed, and review the message on the dashboard's Usage view. |
| Sent but shows no opens | Open tracking fires a pixel that only counts when the recipient loads images. Prefetch opens within seconds of sending are filtered as bots. |
Still stuck?
Every failure returns a stable error.code — look it up in the
error reference for the precise meaning and fix.