API
Catálogo de erros
Cada código de erro do ValorBrain com causa e ação, gerado do catálogo do engine.
Gerado da matriz de credenciais · versão 1 · sha
9d2b630103a5. Não edite à mão: a fonte ésrc/credential-matrix.tsno engine.
Combine pelo código, não pelo texto. O código vem no campo error (ou code) do JSON, no ?error= de um redirect OAuth ou no error= do WWW-Authenticate. Um teste do engine garante que todo código que o servidor devolve está nesta lista.
Códigos
| Código | HTTP | Superfície | Causa | O que fazer |
|---|---|---|---|---|
missing_bearer | 401 | MCP | Requisição ao MCP sem Authorization: Bearer. | Envie um token vbm_ ou siga o WWW-Authenticate para a descoberta OAuth. |
invalid_token | 401 | MCP, REST, Ingest do SaaS, OAuth | Token desconhecido, revogado ou vencido (ou, no MCP, um segredo sem prefixo). | Crie um token novo em Configurações → Tokens MCP ou refaça o signup/consentimento. |
wrong_credential_type | 401 | MCP | Chave REST (vb_, vb_agent_) ou de ingest (fk_) enviada ao MCP. | Use o mcp_token (vbm_…) no MCP e guarde a api_key para o REST. |
agent_key_required | 401 | REST | A reemissão do token MCP do signup (POST /api/v1/agents/mcp-token) recebeu outra credencial que não a vb_agent_ do workspace. | Chame a rota com a api_key (vb_agent_…) que o signup devolveu. |
insufficient_scope | 403 | REST, Ingest do SaaS, Ferramenta MCP | O token é válido mas não tem o escopo exigido pela rota ou ferramenta. | Emita um token com o escopo indicado em required_scope (ou write no ingest). |
credential_required | 403 | REST | Purga de documentos sem credencial bearer. | Envie o token do tenant; dry_run=true funciona sem credencial. |
admin_required | 403 | REST | Operação que exige papel ADMIN do tenant. | Repita com o token de um administrador do workspace. |
attestation_required | 403 | REST | Ato de autoridade Classe A sem X-VB-Attestation. | Envie um envelope de atestação interativo e válido para esta requisição. |
cap_human_forbidden | 400 | REST | Mandato com cap=human: aprovação humana não se delega. | Use um teto abaixo de human. |
identity_denied | 200 | Ferramenta MCP | O token tem scoped_access e a ferramenta pediu uma coleção fora da lista permitida. | Peça ao dono do workspace para incluir a coleção no token. |
scope_denied | 200 | Ferramenta MCP | A ferramenta exige um escopo que o token MCP não tem. | Emita um token com o escopo da ferramenta (Configurações → Tokens MCP). |
outside_keyspace | 200, 403 | REST, Ferramenta MCP | Credencial de integração tentou gravar fora do seu keyspace: um fato com chave fora dele, ou qualquer escrita que não seja fato (documento, mensagem, estado). Nada foi gravado. | Grave só fatos (POST /api/v1/keyed-facts ou upsert_keyed_fact) com chaves do keyspace; para outro keyspace, peça ao admin para ampliar a integração. |
profile_identity_unavailable | 200 | Ferramenta MCP | Perfil de plugin sem identidade de usuário resolvida. | Conecte com um token ligado a um usuário do workspace. |
mcp_init_failed | 403, 500 | MCP | O token pertence a outro destino (audience) ou o transporte MCP não subiu. | Use o token da instância certa; em 500, tente de novo. |
internal_error | 500 | MCP | Falha inesperada ao atender a requisição MCP. | Tente de novo em instantes; se persistir, abra um chamado com o horário da requisição. |
invalid_tenant_header | 400 | REST | X-Tenant-ID não é um UUID de tenant. | Remova o header (o tenant vem da credencial) ou envie um UUID válido. |
invalid_user_header | 400 | REST | X-User-ID não é um UUID de usuário. | Remova o header ou envie o UUID do usuário. |
invalid_member_id | 400 | REST | member_id não é um UUID de membro. | Envie o UUID do membro do time. |
not_document_owner | 403 | REST | POST /documents sobre documento privado de outro usuário, ou mudando a sensibilidade de documento com dono, sem ser o dono com a própria credencial, admin do tenant ou a plataforma; também PUT/DELETE de foundation em documento privado alheio. Nada foi gravado. | Grave com a credencial do dono, de um admin do tenant ou da plataforma, ou use outro caminho. |
sensitivity_change_requires_admin | 403 | REST | POST /documents mudando a sensibilidade de um documento sem dono: rebaixar o abre a tokens restritos, elevar tranca o time fora. Nada foi gravado. | Peça a um admin do tenant, ou grave sem mudar a sensibilidade. |
integration_not_minted_here | 400 | REST | POST /api/v1/mcp/tokens com credential_kind: integration: a credencial de integração nasce com o mandato dela, em outra rota. Nada foi criado. | Crie a integração em POST /api/v1/authority/integrations, ou peça personal ou gateway aqui. |
user_not_in_tenant | 400 | REST, OAuth | Token MCP (ou consentimento OAuth pelo app) pedido para um user_id que não é membro do tenant. | Provisione o usuário antes de emitir o token ou aprovar o consentimento. |
email_already_registered | 409 | REST | O e-mail do administrador já existe em outro tenant. | Entre com a conta existente. |
user_id_conflict | 409 | REST | O e-mail já está ligado a outro id de usuário no tenant. | Use o engine_user_id devolvido. |
rate_limited | 429 | OAuth | Registro dinâmico OAuth acima do limite por IP. | Aguarde o Retry-After e reutilize o client_id já registrado. |
answer_burst_exceeded | 429 | REST | Respostas demais do tenant numa janela curta. | Aguarde o Retry-After. |
answer_cap_reached | 429 | REST | Teto mensal de respostas definido pelo cliente foi atingido. | Aumente ou remova o teto nas configurações. |
not_found | 404, 200 | REST, Ferramenta MCP | Documento, arquivo ou lacuna não existe neste tenant. | Confira o docid/caminho; similarFiles sugere nomes próximos. |
ambiguous | 409 | REST | O nome casa com mais de uma entidade. | Escolha um dos candidates e repita com o id. |
ambiguous_docid | 400 | REST | O prefixo de docid casa com mais de um documento. | Use um prefixo mais longo. |
confirmation_required | 400 | REST | Purga de coleção inteira sem confirm igual ao alvo. | Rode dry_run=true, depois repita com confirm e credencial de admin. |
superseded_document | 404 | REST | O docid é uma versão substituída. | Leia read_at ou o documento vivo em superseded_by. |
supersedes_self | 400 | REST, Ferramenta MCP | supersedes aponta para o próprio documento sendo escrito. | Remova o alvo: reescrever o mesmo caminho já é uma revisão. |
supersedes_invalid | 400 | REST, Ferramenta MCP | Lista supersedes grande demais ou com alvo malformado. | Envie até o máximo de alvos, cada um docid ou caminho. |
supersedes_not_found | 400 | REST, Ferramenta MCP | Um alvo de supersedes não existe. | Confira o docid ou caminho do documento substituído. |
supersedes_ambiguous | 400 | REST, Ferramenta MCP | Um alvo de supersedes casa com mais de um documento. | Use o docid completo ou o caminho. |
revision_conflict | 409 | REST | expected_revision não é a revisão atual. | Releia o documento (current_revision) e reaplique a mudança. |
update_failed | 200 | REST | Um item do lote não pôde ser atualizado. | Repita só os itens com ok: false. |
resolve_failed | 200 | Ferramenta MCP | A lacuna de conhecimento não pôde ser marcada como resolvida. | Tente de novo em instantes; se persistir, abra um chamado com o horário da requisição. |
approval_required | 403, 200 | REST, Ferramenta MCP | Escrita de autoridade mais fraca que o valor vencedor; vira proposta. | Peça aprovação humana ou corrija com assert_authority_correction. |
pii_defense_block | 422 | REST, Ferramenta MCP | Escrita recusada: PII de alto risco que não pôde ir para o cofre. | Remova o dado sensível ou guarde-o com secrets. |
invalid_request | 400, 405 | OAuth | Parâmetro ausente ou inválido (PKCE S256, redirect_uri, corpo do formulário). | Corrija a requisição conforme error_description. |
invalid_client | 401, 400 | OAuth | client_id desconhecido. | Registre o cliente de novo em /oauth/register. |
invalid_client_metadata | 400 | OAuth | Metadados do registro dinâmico inválidos. | Corrija o corpo do /oauth/register. |
invalid_redirect_uri | 400 | OAuth | redirect_uri fora do permitido (http só em loopback; esquemas perigosos recusados). | Use https, loopback ou um esquema próprio do app. |
invalid_grant | 400 | OAuth | Código expirado, já usado, de outro cliente, PKCE errado ou asserção EMA inválida. | Recomece o fluxo de autorização. |
invalid_scope | 400, 302 | OAuth | Escopo pedido fora de read write. | Peça read, write ou ambos. |
invalid_target | 400, 302 | OAuth | resource (RFC 8707) não é um recurso deste emissor. | Use a URL do MCP ou omita resource. |
access_denied | 302 | OAuth | A pessoa recusou o consentimento. | Nada a fazer; ofereça tentar de novo. |
unsupported_grant_type | 400 | OAuth | grant_type diferente de authorization_code ou jwt-bearer. | Use authorization_code com PKCE (ou jwt-bearer no EMA). |
unsupported_response_type | 302 | OAuth | response_type diferente de code. | Use response_type=code. |
method_not_allowed | 405 | OAuth | Endpoint OAuth chamado sem POST. | Use POST. |
server_error | 500 | OAuth | Falha interna no servidor de autorização. | Tente de novo em instantes; se persistir, abra um chamado com o horário da requisição. |
invalid_consent_session | 400 | OAuth | consent_session adulterada, assinada por outra chave ou malformada. | Comece a conexão de novo pelo app (novo /oauth/authorize). |
consent_session_expired | 400 | OAuth | A consent_session passou dos 15 minutos. | Comece a conexão de novo pelo app. |
consent_session_used | 409 | OAuth | Este consentimento já foi decidido (aprovação ou negação é de uso único). | Comece a conexão de novo pelo app. |
tenant_inactive | 403 | OAuth | O workspace da sessão não está com billing_status ativo. | Regularize a assinatura do workspace e aprove de novo. |
unauthorized | 401 | OAuth | Endpoint interno de consentimento chamado sem a credencial de plataforma (só o SaaS chama). | Clientes não chamam este endpoint: use /oauth/authorize. |
Respostas sem código
Alguns portões ainda respondem só com uma mensagem fixa no campo error. A mensagem é estável e pode ser comparada literalmente.
| Código | HTTP | Superfície | Causa | O que fazer |
|---|---|---|---|---|
Unauthorized | 401 | REST | REST sem bearer, ou com uma credencial que não é do REST (fk_, segredo de administração). | Envie Authorization: Bearer vbm_… (ou a vb_agent_ da conta). |
Unauthorized: admin secret required | 401 | REST | Rota de administração da plataforma. | Não é rota de cliente; use as rotas públicas do REST. |
Forbidden: admin credential required for money routes | 403 | REST | Rota de crédito ou assinatura chamada com token de tenant. | Não é rota de cliente; planos se mudam pelo app. |
Forbidden: /metrics is served only to local scrapers | 403 | REST | /metrics fora da rede local e sem o token de métricas. | Não é rota de cliente. |
Rate limit exceeded — please slow down | 429 | REST | Limite por credencial (ou por IP, em rota pública) estourado. | Aguarde retry_after_ms e reduza a cadência. |