Erros

Toda resposta de erro da API — em qualquer rota, qualquer status — usa o mesmo formato. Nunca um HTML de erro, nunca um corpo vazio.

{
  "error": {
    "code": "forbidden_scope",
    "message": "Esta chave não tem o escopo contacts.write.",
    "request_id": "a1b2c3d4e5f6"
  }
}

code é estável — pode basear lógica em cima dele (retry, mensagem pro seu usuário). message é pra humano, em português, pode mudar de texto sem aviso.

Reportando um erro pra gente

Toda resposta — erro ou sucesso — já vem com o header x-request-id, e ele também aparece dentro do corpo do erro como request_id (o mesmo valor nos dois lugares). Se algo falhar de um jeito que não faz sentido, esse id é o que a gente precisa pra achar exatamente a chamada nos nossos registros — bem mais rápido que descrever "por volta de tal hora, chamando tal rota".

Codes por status