Errors
Every error under /api/v1/partner/email/ has a stable error code + a
human-readable message. Build retry / error-handling logic against
the code, not the message.
Response shape
{
"success": false,
"error": "FROM_NOT_VERIFIED",
"message": "from address is not on a verified identity"
}success: false is always present. error is the stable code.
message is for display + may change for clarity over time. A few
errors add detail, such as ip, limit or results.
Two answers don't have this shape: 429 rate_limit_exceeded (below)
and a URL that doesn't exist, which answers a plain-text 404.
An error we have no specific code for gets the plain code of its
status: INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND,
CONFLICT, RATE_LIMITED, INTERNAL_ERROR or SERVICE_UNAVAILABLE.
400 Bad Request
401 Unauthorized
402 Payment Required
403 Forbidden
404 Not Found
409 Conflict
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable
Connected apps
Calls made with a connected app token (spo_at_...) can also get
these lower-case codes:
SMTP errors (in webhook payloads)
When a Bounce event fires, the bounce.bouncedRecipients[].diagnosticCode
field carries the SMTP diagnostic from the recipient's MX. Common ones:
Retry strategy
Rule of thumb:
- 400-class errors: don't retry. Fix the request.
- 402: don't retry. Recharge first.
- 403 + 404: don't retry. Fix configuration first.
- 429: retry with exponential backoff (start 1s, double up to 60s),
except
SANDBOX_QUOTA_REACHED,DAILY_LIMIT_REACHEDanddaily_send_limit: those last until the cap resets. - 500 / 503: retry up to 3 times with exponential backoff, except
RENDER_FAILED.
Idempotency: /send is NOT idempotent on retry — duplicate calls
with the same body will produce duplicate email sends. Implement
your own dedup against your business identifier (charge_id, etc.)
before calling /send.
When to contact support
- 500-class errors persist > 5 minutes
- 402 even though wallet balance shows positive
- 403 SENDING_PAUSED with no clear cause in
/reputation
Email [email protected] or open a ticket in Splashify Pro Email.