Erros
A API pública usa códigos de estado HTTP estáveis e um envelope de erro legível por máquina. Quem usa o SDK recebe um FabHubApiError tipado para qualquer resposta não 2xx.
Forma do erro
{
"error": {
"code": "SCOPE_REQUIRED",
"message": "This credential is missing the items:write scope",
"request_id": "req_8f3a...",
"details": {}
}
}
request_id é incluído na maioria das respostas - cite-o nos pedidos de suporte. details está presente para erros de validação. Ramifique pelo error.code estável, não pela message.
Códigos de estado
| Estado | Significado |
|---|---|
400 | Pedido inválido ou erro de validação |
401 | Credencial em falta, inválida, expirada ou revogada |
403 | Scope em falta, bloqueio de plano ou recusa por lista de IPs permitidos |
404 | Recurso não encontrado |
409 | Conflito de idempotência (chave reutilizada com um payload diferente) |
429 | Limite de taxa excedido |
500 | Erro do servidor |
Códigos de erro
BAD_REQUEST,UNAUTHORIZED,FORBIDDEN,NOT_FOUND,CONFLICT,RATE_LIMITED,INTERNAL_ERRORSCOPE_REQUIRED- a credencial não tem um scope necessárioPLAN_REQUIRED- o plano do tenant não inclui esta capacidadeOBJECT_ACCESS_DENIED- o objeto referenciado está fora do tenantTENANT_DISABLED,ENDPOINT_DISABLED- interruptores de emergênciaMCP_CONFIRMATION_REQUIRED- uma ferramenta MCP de escrita/destrutiva precisa de confirmação explícita
Exemplos
{ "error": { "code": "NOT_FOUND", "message": "Item not found", "request_id": "req_1a..." } }
{ "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded; retry after the window resets", "request_id": "req_2b..." } }
Orientações para o cliente
Trate 401 e 403 como problemas de configuração ou permissão, não como falhas repetíveis. Trate 429 como repetível apenas depois de a janela de limite de taxa reiniciar. Use chaves de idempotência nas escritas para poder repetir em segurança falhas de transporte. Consulte Idempotência e Limites de Taxa.