Erros

Toda recusa tem um só formato, em qualquer superfície:

{
  "error": {
    "code": "conflict",
    "message": "Outra pessoa salvou este arquivo antes. Leia de novo, refaça a sua mudança sobre a nova versão e salve.",
    "retryable": true,
    "currentVersion": 4
  }
}

Onde aparece. Em um resultado de ferramenta com isError: true, como o texto do resultado; no data de um erro JSON-RPC, então error.data.error o traz e o error.code JSON-RPC continua numérico; e como corpo da resposta de um link de envio ou de download, com o status HTTP que cabe ao código.
code. Minúsculas com sublinhado, como invalid_arguments, unknown_tool, organization_inactive, rate_limited, credits_exhausted ou internal. Decida pelo code; o conjunto é fixo.
message. Uma frase simples no idioma do pedido, que termina com o próximo passo. Nunca começa com o código.
retryable. Sempre true ou false. Com true, repita a chamada, depois de retryAfterSeconds quando ele vier.
Detalhes. Junto dos três campos, uma recusa pode trazer currentVersion (a versão sobre a qual refazer a mudança), retryAfterSeconds, failingRecords (os registros que falharam, em um lote) e issues (cada campo inválido e o que ele espera).

Uma falha que a Siglata não esperava responde internal, com retryable verdadeiro e uma mensagem genérica: ela nunca traz texto do banco, de fornecedor ou de pilha.