statusCode field, and name is a stable, machine-readable error type you can branch on.
Error codes
Authentication and account-state problems all report the single
invalid_api_key name. mailkube does not distinguish them, to avoid leaking account state to an unauthenticated caller.Handling errors
Branch onstatusCode first, then on name for 400, 403, 404, 409, and 422 responses:
- On a 400, fix the request envelope: add a
User-Agent, shorten theIdempotency-Key, or send a well-formed JSON body. - On a 403, fix the credential, or stop calling from a browser; do not retry unchanged.
- On a 404, fix the
template_id/template_version, or the scheduled-email id (scheduled_email_not_found); do not retry unchanged. - A 409 is an idempotency conflict: reuse a key only for the identical retry, and wait for an in-flight request to finish.
- On a 422, fix the request; the
namesays what (a field, atopic, a plan limit, quota, a template, the message content, a blocked link, or a scheduled email that is no longer pending). The same request gets the same rejection. Plan-limit and quota failures need a smaller send or a plan change. See Plans & limits. Ascheduled_email_not_pendingcannot be retried, because the email already left thescheduledstate.template_render_failedandtemplate_variables_too_largeare permanent too: the first needs a fixed template, the second a smallervariablesobject. - On a 405, use one of the methods listed in the
Allowresponse header for that endpoint. - On a 406, drop the
Acceptheader or set it toapplication/json. - On a 415, send the body as
Content-Type: application/json. - On a 429, back off and retry after
Retry-After. - On a 500, retry with backoff.
X-Request-Id header; it identifies the exact request.