Erros e limites
O formato dos erros, cada código, idempotência e os limites de chamadas.
Formato
Todo erro tem o mesmo formato:
{ "error": { "code": "not_found", "message": "No such contact." } }| Campo | O que é |
|---|---|
code | Um código estável, em inglês, feito para o seu código comparar. |
message | Uma explicação para pessoas. Pode mudar; não compare. |
Alguns erros trazem um campo a mais, como o contact_id em phone_taken.
Códigos
| Status | Códigos | Quando |
|---|---|---|
400 | invalid_json, invalid_cursor, invalid_query, invalid_idempotency_key | O corpo, o cursor, a query ou a Idempotency-Key não é válido |
401 | unauthorized | Token ausente, desconhecido, expirado ou revogado |
403 | forbidden | Falta o escopo, ou o membro que autorizou não tem a permissão |
404 | not_found | O endpoint não existe, ou o item não é do workspace |
405 | method_not_allowed | O método não existe neste endpoint |
409 | phone_taken, taken, quota, opted_out, open_item_exists, invalid_state, draft | O estado atual impede a ação: telefone ou nome já usado, limite do plano cheio, contato descadastrado, negócio aberto no pipeline, campanha no estado errado |
422 | invalid, invalid_phone, limit, in_the_past, group_left, audience_too_large, idempotency_mismatch | O corpo não é válido para a ação |
429 | rate_limited | Limite de requisições |
Cada endpoint lista os seus na Referência da API.
Idempotência
Toda escrita (POST, PUT, PATCH, DELETE) aceita o cabeçalho Idempotency-Key. Com ele, repetir a chamada (depois de um timeout, por exemplo) devolve a primeira resposta em vez de fazer de novo.
- Até 200 letras, dígitos,
-ou_. Outro formato recebe400cominvalid_idempotency_key. - A primeira resposta fica guardada por 24 horas. Uma repetição a recebe de volta, com o mesmo status, e o cabeçalho
Idempotent-Replayed: true. - A chave vale para o mesmo método, caminho e corpo. Usar a mesma chave em outra requisição recebe
422comidempotency_mismatch. - Duas chamadas simultâneas com a mesma chave não executam duas vezes: a segunda espera a primeira e recebe a resposta dela.
- As chaves são de cada chave de API (ou de cada autorização OAuth); outra credencial não vê as suas.
Limites
- API: cada chave de API, e cada conexão OAuth (app, pessoa e workspace), faz até 600 requisições por minuto. Acima disso, a resposta é
429comrate_limitede o cabeçalhoRetry-After, em segundos. - MCP: cada conexão (app, pessoa e workspace) faz até 60 chamadas por minuto. Veja Servidor MCP.
- Webhooks de saída: o plano limita os endpoints de um workspace. Veja webhooks.
Na API, ao receber 429, espere os segundos de Retry-After e tente de novo.