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 responde 401. Chave desconhecida ou revogada também, com o mesmo corpo para as duas: 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. Ramifique pelo código, não pela mensagem.

{
  "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), uma regra que a API confere antes da Meta (recipient_invalid, meta_window_closed) ou uma recusa da Meta traduzida num código meta_ (meta_account_blocked, meta_unknown).
• 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, com Retry-After dizendo quanto esperar, ou um limite de taxa da Meta (meta_rate_limited, meta_spam_rate_limited, meta_user_frequency_cap, meta_pair_rate_limited), sem o header.
• 500: 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 dos quatro códigos meta_ de taxa, sem Retry-After. O evento de teste de webhook tem orçamento próprio: 30 por hora.