Errors & Status Codes #

HTTP status codes #

Failures return a standard HTTP status with success: false and a messages array explaining what went wrong.

Status	Meaning	What to do
`400`	Bad request — missing/invalid parameter	Check `messages`; fix the parameter
`401`	Missing or invalid API key	Verify your `Authorization: Bearer …` header
`403`	Authenticated, but not allowed for this account	The resource isn't yours, or the feature isn't enabled
`404`	Not found / not owned by your account	Check the ID; you can only access your own data
`422`	Validation failed	e.g. a required field or custom field is missing
`429`	Rate limited	Back off and retry after a short delay

{ "success": false, "data": null, "messages": ["Missing or invalid recipientEmail parameter"] }

Send eCard outcomes #

POST /pub/ecard-actions/send-ecard returns success: true on a successful send. When a send is rejected, success is false and messages explains why. Common reasons:

Reason	Meaning
`wouldexceedlimit`	Not enough emails left in your plan's billing period
`toomany`	Too many recipients for this send
`tooshort`	No recipients provided
`einvalid`	Sender email is invalid
`finvalid`	A recipient email is invalid
`limitReached`	Rate limit exceeded — slow down
`blocked`	Flagged by anti-spam (rare false positive — contact support)
`spammer`	Send rejected (unspecified send error)

Downstream email-delivery errors (e.g. from Postmark) aren't a code — they surface as a human-readable string in messages. Always read messages for the specifics.

A successful email send reports emailsSent: 1 (per recipient). A successful share-link send returns shareUrl + statVanityId and no email is sent. See Send eCards via API.

Tips #

Always check success (and HTTP status) before trusting data.
Surface messages[0] to your logs/users — they're human-readable.
For transient failures (429, delivery errors), retry with backoff.