Errors

Sendivent uses standard HTTP status codes. Error responses include a human-readable error message.

WARNING

The error string is for humans and may change. For programmatic handling, use the HTTP status code and any structured fields (field, channel, current, limit) when present.

Error response format

{
  "error": "Event 'welcome' not found"
}

Some errors include additional fields:

Field	When included
field	Validation error on a specific field
channel	Channel-specific error
current, limit	Quota/limit errors

HTTP status codes

Status	Meaning
400	Bad request — your input is invalid
401	Unauthorized — API key missing or invalid
402	Payment required — quota exceeded
403	Forbidden — subscription inactive
404	Not found — resource doesn't exist
409	Conflict — duplicate request
429	Too many requests — rate limited
5xx	Server error — our system or provider failed

Common errors

Invalid API key

Status: 401

{
  "error": "Invalid API key"
}

Fix: Copy key from dashboard. Use Authorization: Bearer YOUR_KEY header.

---

Event not found

Status: 404

{
  "error": "Event 'welcome' not found"
}

Fix: Create event in dashboard or check spelling. Verify environment matches (sandbox key → sandbox events).

---

Contact not found

Status: 404

{
  "error": "Contact not found: user_123"
}

Note: This error only occurs when looking up a contact via GET /v1/contacts/:identifier. The send API (POST /v1/send/{event}) automatically creates contacts if they don't exist.

Fix: Verify the external_id or email exists in your dashboard.

---

Validation error

Status: 400

{
  "error": "Phone number must be in E.164 format",
  "field": "to"
}

Fix: Check the field mentioned. Phone numbers need + and country code.

---

Quota exceeded

Status: 402

{
  "error": "Monthly notification quota exceeded",
  "current": 10000,
  "limit": 10000
}

Fix: Upgrade your plan or wait for quota reset.

---

Rate limited

Status: 429

{
  "error": "Rate limit exceeded"
}

Fix: Implement exponential backoff. Check Retry-After header.

---

No template for channel

Status: 400

{
  "error": "Event \"reminder\" has no sms template configured"
}

Fix: Add a template for this channel in the dashboard, or remove .channel() to let Sendivent auto-select.

---

Unverified sender

Status: 400

{
  "error": "Sender '+14155551234' is not verified. Register and verify it first in your dashboard."
}

Fix: Register and verify the sender in Channels (Email for domains, SMS for phone numbers).

---

Subscription inactive

Status: 403

{
  "error": "Subscription is not active"
}

Fix: Check your subscription status in Settings → Billing. Reactivate or update payment method.

---

Duplicate request

Status: 409

{
  "error": "Delivery already sent"
}

Note: This occurs when using idempotency keys. The original request succeeded; this duplicate was rejected.

Fix: This is expected behavior. Check your Activity log for the original delivery.

---

Provider error

Status: 502

{
  "error": "Email provider error: Service temporarily unavailable"
}

Note: The external provider (email, SMS, or Slack) returned an error. These are typically transient.

Fix: Retry the request. If persistent, check the provider's status page or contact support.

Request correlation

When contacting support, include:

• The timestamp of the failed request
• Your request payload
• The delivery ID from the Activity log (if available)

See also

• Troubleshooting — common issues and fixes
• Rate Limits — request limits by plan