Errors

All Numonic API errors follow a consistent format with machine-readable codes and developer-friendly context.

Error format

{
  "success":   false,
  "error": {
    "code":    "DOMAIN_NOT_VERIFIED",
    "message": "The from address domain is not verified",
    "why":     "The domain example.com has not completed DNS verification",
    "action":  "Add the required DNS records and wait for verification to complete"
  },
  "timestamp": "2026-04-09T10:30:00.000Z",
  "path":      "/api/v1/send"
}

The why and action fields are included on most errors to give you a clear explanation of what went wrong and what to do about it.

Error codes

Code	HTTP Status	Description
`BAD_REQUEST`	400	Malformed request
`DOMAIN_NOT_VERIFIED`	400	Sending from a domain that hasn’t completed verification
`UNAUTHORIZED`	401	Missing or invalid credentials
`FORBIDDEN`	403	Insufficient permissions
`DOMAIN_NOT_OWNED`	403	Domain belongs to another tenant
`NOT_FOUND`	404	Resource not found
`ROUTE_NOT_FOUND`	404	Unknown endpoint
`CONFLICT`	409	Resource conflict — e.g. domain already registered, or idempotency key reused with a different payload
`VALIDATION_ERROR`	422	Request body validation failed — missing required fields or invalid format
`RATE_LIMIT_EXCEEDED`	429	Too many requests — back off and retry
`INTERNAL_ERROR`	500	Server error
`UPSTREAM_ERROR`	502	Upstream service (SES) returned an error
`UPSTREAM_UNREACHABLE`	503	Upstream service timed out

Rate limits

Window	Limit
Per second (burst)	3 requests
Per 10 seconds	20 requests
Per minute	100 requests

When rate limited, you’ll receive 429 RATE_LIMIT_EXCEEDED. Use exponential backoff and retry.

Getting Started

API Reference

Errors

Errors

Error format

Error codes

Rate limits

​Errors

​Error format

​Error codes

​Rate limits

Errors

Error format

Error codes

Rate limits