Errors & limits

Errors return JSON with a human message and a stable code: { "error": "...", "code": "quota_exceeded" }. Handle codes, not messages.

Error codes

StatusCodeMeaning
401invalid_keyThe API key is missing, malformed, or revoked.
402billing_requiredProduction sending requires an active Free, Pro, or Custom workspace.
403quota_exceededMonthly quota (or the pay-as-you-go safety ceiling) reached.
403account_pausedThe deliverability autopilot paused sending; check Metrics.
403attachments_require_proOutbound REST attachments require Pro or Custom.
403contact_limit_reachedYour plan's contact allowance is full.
403domain_limit_reachedYour plan's sending or receiving domain allowance is full.
403project_requiredChoose a project with X-NoticeAPI-Project-ID or use a project-bound key.
403project_not_allowedThe API-key grant cannot access the selected project.
403domain_not_allowedThe API-key grant cannot use the selected sender domain.
403insufficient_scopeThe API key doesn't carry the scope this endpoint requires.
404audience_not_foundThe audience id does not exist in this workspace.
404broadcast_not_foundThe broadcast id does not exist in this workspace.
404contact_not_foundThe contact id does not exist in that audience.
404not_foundThe requested template, received email, attachment, or suppression was not found.
409domain_not_readyThe from-domain isn't verified yet.
409idempotency_mismatchThat Idempotency-Key was already used with a different send payload.
409recipient_suppressedA recipient is on your suppression list.
409duplicate_audienceAn audience with that name already exists.
409duplicate_templateA template with that name already exists.
409broadcast_not_draftBroadcasts can only be sent once.
409broadcast_not_deletableOnly draft or scheduled broadcasts can be deleted.
409broadcast_not_schedulableOnly draft or scheduled broadcasts can be scheduled.
409broadcast_not_scheduledOnly scheduled broadcasts can be canceled.
409email_not_cancelableOnly scheduled transactional emails can be canceled.
409email_not_reschedulableOnly scheduled transactional emails can be rescheduled.
422invalid_schedulescheduledAt is missing, invalid, in the past, or more than 30 days out.
422invalid_payloadValidation failed; the error message says which field.
422invalid_fromThe sender address could not be parsed.
422invalid_idempotency_keyIdempotency-Key must be at most 256 characters.
422mixed_simulationSimulator and real recipients can't share one send.
422unknown_simulationA simulator recipient must use delivered@, bounced@, complained@, or suppressed@.
429daily_limit_reachedWarm-up ramp or plan daily cap hit; limits grow automatically.
429rate_limitedToo many requests; respect Retry-After.

Limits

Recipients per message10 across to/cc/bcc
Batch size100 emails per call
Content sizehtml ≤ 1MB, text ≤ 500KB, attachments ~5MB decoded total
API rate120 requests/min per key on send (Free also has a 30/min workspace guardrail); Retry-After on 429
Idempotency keys≤ 256 chars, replay returns the original result
OveragePro keeps sending past included usage at published overage rates up to a safety ceiling support can raise