Errors and rate limits

API errors contain code and message. Field validation errors also include an errors object. Use code in your application rather than matching message text.

{
  "code": "validation_error",
  "message": "The given data was invalid.",
  "errors": {"to": ["The to field must be a valid email address."]}
}

HTTP	Code	Action
401	invalid_api_key	Check that the key is correct and active.
402	payment_required	Complete the payment in workspace Billing.
403	access_denied	Check workspace status, sending plan, and access to the requested feature.
404	not_found	Check the message ID and project key.
409	idempotency_conflict	Restore the original payload for a retry. Use a new key only for a new email.
413	request_too_large	Reduce the JSON request body to 8 MB or less.
422	validation_error	Check the fields, required variables, published template language, and sending setup.
429	email_capacity_exceeded	Enable automatic email purchases or upgrade in Billing.
429	rate_limited	Wait for Retry-After before retrying.
500, 502, 503, 504	server_error	Retry after a delay using the same key and payload.

Sending emails and checking their status count toward the same limits:

Scope	Requests per minute
Per project, shared across all API keys	120
Per IP address	600

• If you receive a rate_limited error, wait for the delay in the Retry-After header (in seconds), then retry the same request.
• If you receive an email_capacity_exceeded error, enable automatic email purchases or upgrade your plan in Billing.

SDKs expose the HTTP status, error code, field errors, and retry delay. A status of 0 is an SDK error: connection_error means the request could not complete, and invalid_response means the response could not be read. The send may still have been accepted. Retry with the original key and payload.