Erros

Todo erro da API devolve um corpo JSON com error e message. O error é um código estável, pensado para o seu código decidir o que fazer. O message é texto para uma pessoa ler, em português.

O formato do erro

{
  "error": "invalid_request",
  "message": "Requisição inválida.",
  "campos": [{ "campo": "text.body" }]
}

• Decida pelo error e pelo status, nunca pelo texto do message.
• Alguns erros acrescentam campos que dizem o que fazer: campos, fechadaEm, acaoRecomendada, estado, faltando, tentativasRestantes, janelaVira, reenfileiradoEm e credentialStatus. Eles estão na tabela abaixo.
• Nenhum erro repete de volta o valor que você mandou. Num 400, o que sai é o caminho do campo recusado, e nunca o conteúdo.
• 404 vale também para um recurso que existe e não é seu. A API não confirma a existência de recurso de outro cliente, nem pelo status.

Os códigos principais

Os quatro códigos 429 têm origem diferente, e a resposta traz o Retry-After, em segundos. Se ele faltar, espere com recuo crescente, como o código abaixo faz. O 429 da Luna nunca é o limite de ritmo da Meta devolvido a você: esse limite é resolvido por fila, e por isso o envio responde 202.

O limite de requisições

Cada chave de API pode fazer 600 requisições por minuto. O limite é técnico e idêntico para todos os clientes. Nenhum limite desta plataforma varia por preço. Requisição sem chave é contada pelo endereço de origem.

• Os três X-RateLimit-* acompanham as respostas bem-sucedidas. Leia X-RateLimit-Remaining e desacelere antes de chegar a zero.
• Num 429, espere o Retry-After. Retentar na hora só é recusado de novo.
• O cadastro de conta tem um teto próprio: 5 por hora por endereço de origem.

Retentar com segurança

Repita só 429 e 503, e espere o Retry-After. Para POST /v1/messages, mande sempre o Idempotency-Key, e o mesmo em todas as tentativas: sem ele, uma retentativa depois de um tempo esgotado pode enviar a mensagem duas vezes. Não repita 400, 401, 403, 404 nem 409: a resposta não muda.

const BASE = 'https://api.lunahia.com.br';

async function lunaFetch(path, options = {}, attempts = 5) {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(`${BASE}${path}`, {
      ...options,
      headers: {
        Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
        'Content-Type': 'application/json',
        ...options.headers,
      },
    });

    const retryable = res.status === 429 || res.status === 503;
    if (!retryable || attempt === attempts) return res;

    // Retry-After is in seconds. Without it, back off 2, 4, 8... seconds.
    const wait = Number(res.headers.get('retry-after')) || 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
}

// One Idempotency-Key for all attempts, so a retry never sends twice.
const res = await lunaFetch('/v1/messages', {
  method: 'POST',
  headers: { 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    from: 'YOUR_PHONE_NUMBER_ID',
    to: '5511999990000',
    text: { body: 'Olá!' },
  }),
});

const body = await res.json();
if (!res.ok) {
  console.error(res.status, body.error, body.message);
} else {
  console.log(res.status, body);
}

import os
import time
import uuid

import requests

BASE = "https://api.lunahia.com.br"


def luna_request(method, path, attempts=5, **kwargs):
    headers = {
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
        **kwargs.pop("headers", {}),
    }
    for attempt in range(1, attempts + 1):
        res = requests.request(
            method, BASE + path, headers=headers, timeout=10, **kwargs
        )
        if res.status_code not in (429, 503) or attempt == attempts:
            return res
        # Retry-After is in seconds. Without it, back off 2, 4, 8... seconds.
        time.sleep(int(res.headers.get("Retry-After", 2**attempt)))


# One Idempotency-Key for all attempts, so a retry never sends twice.
res = luna_request(
    "POST",
    "/v1/messages",
    headers={"Idempotency-Key": str(uuid.uuid4())},
    json={
        "from": "YOUR_PHONE_NUMBER_ID",
        "to": "5511999990000",
        "text": {"body": "Olá!"},
    },
)

body = res.json()
if not res.ok:
    print(res.status_code, body["error"], body["message"])
else:
    print(res.status_code, body)

Quando a mensagem é aceita e depois falha

O 202 do envio quer dizer que a Luna aceitou a mensagem, e não que ela foi entregue. A falha pode vir depois, da Meta. Você a vê de duas formas: no webhook, com um message.status de status: "failed" e o error_code, e em GET /v1/messages/{id}, no campo erros.

{
  "codigo": 131026,
  "categoria": "nao_entregavel",
  "mensagem": "O destinatário não pode receber esta mensagem: o número não tem WhatsApp, ou não existe.",
  "acaoRecomendada": "Confira o número do destinatário e reenvie para o número correto. Repetir o envio para o mesmo número não muda o resultado.",
  "original": {
    "error": {
      "message": "Message undeliverable",
      "type": "OAuthException",
      "code": 131026,
      "fbtrace_id": "EXAMPLE_TRACE_ID"
    }
  }
}

• desconhecido é literal e deliberado: a Meta acrescenta códigos sem aviso, e um código ainda não mapeado chega com essa categoria em vez de ser escondido. Leia o codigo e o original.
• erros reúne o que a Meta recusou na hora do envio e o que ela informou depois, por evento de status. Você não precisa saber de qual dos dois veio cada item: a acaoRecomendada é a que resolve.
• Cuidado ao repassar `original`. Ele pode conter o telefone do consumidor final e trechos da conversa. Trate-o com o cuidado do restante do conteúdo das mensagens antes de mandá-lo a terceiros.
• Ao pedir ajuda à Meta, o fbtrace_id dentro de original é o que faz um chamado avançar.