Erros
Formato dos erros e lista de códigos retornados pela API e pelo MCP.
Toda resposta de erro tem o mesmo formato:
{
"error": {
"code": "conflict",
"message": "O roteiro mudou em outro lugar. Revise antes de substituir.",
"details": {}
}
}Código estável, próprio para tratamento no seu código.
Mensagem em português, pensada para pessoas. Pode mudar sem aviso; não use em comparações.
Opcional. Informações extras, como a versão atual em conflitos ou os campos inválidos.
No MCP, o mesmo objeto chega no resultado da ferramenta, com isError: true.
Códigos
| Status | Código | Significado |
|---|---|---|
400 | invalid_body | A requisição não tem corpo. |
400 | invalid_json | O corpo não é um JSON válido. |
401 | unauthorized | Credencial ausente ou token OAuth inválido, expirado ou revogado. Entre novamente. |
401 | invalid_token | Chave inválida, expirada, revogada ou do tipo errado, ou header Authorization malformado. |
403 | insufficient_scope | Falta um escopo. details.scope indica qual. |
403 | web_session_required | A ação só pode ser feita pela sessão web (chaves, webhooks, dados da conta). |
403 | invalid_origin | Origem não permitida (MCP ou mutações da web). |
403 | invalid_host | O MCP foi acessado por um host diferente do oficial. |
404 | not_found | Recurso inexistente ou de outra conta. |
409 | conflict | Revisão desatualizada, roteiro no estado errado ou id já usado. details.current traz a versão salva. |
413 | body_too_large | Corpo acima de 1 MB. |
415 | unsupported_media_type | Envie Content-Type: application/json. |
422 | invalid_input | Campos inválidos. details lista os problemas. |
422 | invalid_query | Parâmetros de query inválidos (cursor, limit, deleted). |
429 | rate_limited | Limite por conta atingido. details.retryAfter e o header Retry-After indicam a espera. |
500 | internal_error | Falha inesperada. Tente novamente. |
Erros de validação
Em invalid_input, details separa erros gerais (formErrors) e erros por campo (fieldErrors):
{
"error": {
"code": "invalid_input",
"message": "Confira os campos do roteiro.",
"details": {
"formErrors": [],
"fieldErrors": {
"title": ["O título pode ter até 160 caracteres."],
"expectedRevision": ["Invalid input: expected number, received undefined"]
}
}
}
}Campos desconhecidos no corpo também geram invalid_input: envie apenas os campos documentados.
Respostas 401
Respostas 401 incluem WWW-Authenticate: Bearer realm="LiveTP". No MCP, o header aponta para os metadados OAuth (resource_metadata), permitindo que o cliente inicie o login.