Skip to main content

​
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

CodeHTTP StatusDescription
BAD_REQUEST400Malformed request
DOMAIN_NOT_VERIFIED400Sending from a domain that hasn’t completed verification
UNAUTHORIZED401Missing or invalid credentials
FORBIDDEN403Insufficient permissions
DOMAIN_NOT_OWNED403Domain belongs to another tenant
NOT_FOUND404Resource not found
ROUTE_NOT_FOUND404Unknown endpoint
CONFLICT409Resource conflict — e.g. domain already registered, or idempotency key reused with a different payload
VALIDATION_ERROR422Request body validation failed — missing required fields or invalid format
RATE_LIMIT_EXCEEDED429Too many requests — back off and retry
INTERNAL_ERROR500Server error
UPSTREAM_ERROR502Upstream service (SES) returned an error
UPSTREAM_UNREACHABLE503Upstream service timed out

​
Rate limits

WindowLimit
Per second (burst)3 requests
Per 10 seconds20 requests
Per minute100 requests
When rate limited, you’ll receive 429 RATE_LIMIT_EXCEEDED. Use exponential backoff and retry.