Skip to main content
When a request fails, the API returns a compact JSON envelope. The HTTP status code is mirrored in the 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 on statusCode first, then on name for 400, 403, 404, 409, and 422 responses:
  • On a 400, fix the request envelope: add a User-Agent, shorten the Idempotency-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 name says what (a field, a topic, 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. A scheduled_email_not_pending cannot be retried, because the email already left the scheduled state. template_render_failed and template_variables_too_large are permanent too: the first needs a fixed template, the second a smaller variables object.
  • On a 405, use one of the methods listed in the Allow response header for that endpoint.
  • On a 406, drop the Accept header or set it to application/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.
When you report a failure to support, include the response’s X-Request-Id header; it identifies the exact request.