Autenticação

Toda requisição leva a chave de API no header Authorization como bearer. As chaves começam com zp_ e têm 256 bits de entropia; guardamos só o hash SHA-256 delas, então um banco vazado não vaza chaves.

Authorization: Bearer zp_...

• Chave ausente, desconhecida ou revogada responde 401 com o mesmo corpo: a API não confirma quais chaves existem.
• Conta sem assinatura ativa responde 402 com o código subscription_required. Não há período grátis: a conta assina pelo menos um número para abrir o console. Os números continuam conectados; assinar libera na chamada seguinte.
• Revogar uma chave no console vale na requisição seguinte. Chave não tem escopo: uma chave abre a conta inteira, então mantenha uma por ambiente e rotacione criando a nova antes.

Erros

Toda resposta que não é 2xx é um objeto com o campo error, que carrega um código estável, uma mensagem em inglês e, quando ajuda, details. O código é o que o seu código deve testar.

{
  "error": {
    "code": "validation_failed",
    "message": "The request body does not match the schema.",
    "details": { "path": "message.text", "expected": "string", "got": "undefined" },
    "docs": "https://zaiped.com/developers/docs"
  }
}

• 400: JSON inválido, corpo que não casa com o schema da rota (validation_failed, com o caminho) ou uma regra que a API confere antes da Meta (por exemplo recipient_invalid, meta_window_closed).
• 401 e 402: autenticação e direito de uso, como acima.
• 404: a rota não existe, ou o id é de outra conta (nunca distinguimos os dois).
• 429: um orçamento da Zaiped ou um limite de taxa da Meta. Leia o Retry-After e espere.
• 502 e 500: a Meta recusou de um jeito que não soubemos traduzir, ou falhamos. Retente com backoff.

Limites de taxa

Por conta: 600 requisições por minuto, mais um orçamento de envio de 1.000 mensagens por hora e 5.000 por dia. A Meta aplica os limites dela por número por cima; eles voltam como 429 com um código meta_.