Bad requests
A 400 means the request never reached the part of the system that could have
accepted it. Nothing was queued, nothing was charged, and retrying the same
body will fail the same way.
Malformed JSON
{ "status": 400, "title": "Invalid JSON body", "detail": "..." }
The most common error in the API by a wide margin. detail carries the
decoder’s own message, which names the offset or the token, and that message
is the useful part even though you should not match on it.
Usual causes, in the order they occur in practice: a trailing comma, a
single-quoted string, an unescaped newline inside a value, and a body that was
never sent at all because the client set Content-Type but no payload.
A field of the wrong type
Type errors are mapped to the JSON field rather than the Go struct behind it, so the message names something you wrote:
{ "status": 400, "title": "Invalid variables",
"detail": "Template variables must be strings. Quote every value..." }
variables is the one that catches people, because a number or a boolean in
that object is the natural thing to write:
{ "variables": { "order_id": 1234 } } // refused
{ "variables": { "order_id": "1234" } } // correct
Missing Idempotency-Key
{ "status": 400, "title": "Missing Idempotency-Key",
"detail": "All /v1/send calls require an Idempotency-Key header (any unique string per send, 24h dedupe window)." }
It is required, not optional, on both send endpoints. Any unique string per send. See Idempotency.
Too many recipients
The hard cap is 100 across To, Cc and Bcc on one send. Over 25 the send
still succeeds and comes back with a warning field.
{ "status": 400, "title": "Too many recipients", "detail": "..." }
If you are near the cap, you want batch sending instead, which is also the shape that gets you per-recipient results.
Invalid email
Addresses are checked for local@domain shape before anything else happens.
This catches the pasted <name@example.com> with the angle brackets left in,
and the trailing comma from a split list.
Scheduling errors
send_at must be RFC3339 and not more than 30 days ahead:
{ "status": 400, "title": "Invalid send_at",
"detail": "send_at cannot be more than 30 days in the future." }
A timestamp in the past is not an error. It sends immediately, on the reasoning that a scheduler running slightly late should still deliver.
What a 400 never means
It never means “try again later”. Nothing about the request is transient: the body is wrong, and the same body will be wrong next time. Retrying a 400 on a backoff is a loop that ends when your retry budget does.
The statuses worth retrying are 429, 500, 502 and 503. See
Timeouts and server errors.