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 64 KiB 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 and status requests share a limit of 120 requests per minute per project, across all its API keys. There is also a limit of 600 requests per minute per IP address. A rate_limited response includes a Retry-After header with the delay in seconds. An email_capacity_exceeded response requires a billing action; waiting does not add capacity.

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.