Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      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.