Errori
L'API pubblica usa codici di stato HTTP stabili e un involucro di errore leggibile dalla macchina. I chiamanti dell'SDK ricevono un FabHubApiError tipizzato per qualsiasi risposta non-2xx.
Forma dell'errore
{
"error": {
"code": "SCOPE_REQUIRED",
"message": "This credential is missing the items:write scope",
"request_id": "req_8f3a...",
"details": {}
}
}
request_id è incluso nella maggior parte delle risposte - citalo nelle richieste di supporto. details è presente per gli errori di validazione. Diramati sul error.code stabile, non sul message.
Codici di stato
| Stato | Significato |
|---|---|
400 | Richiesta non valida o errore di validazione |
401 | Credenziale mancante, non valida, scaduta o revocata |
403 | Scope mancante, blocco del piano o rifiuto dell'allowlist IP |
404 | Risorsa non trovata |
409 | Conflitto di idempotenza (chiave riutilizzata con un payload diverso) |
429 | Rate limit superato |
500 | Errore del server |
Codici di errore
BAD_REQUEST,UNAUTHORIZED,FORBIDDEN,NOT_FOUND,CONFLICT,RATE_LIMITED,INTERNAL_ERRORSCOPE_REQUIRED- alla credenziale manca uno scope richiestoPLAN_REQUIRED- il piano del tenant non include questa funzionalitàOBJECT_ACCESS_DENIED- l'oggetto referenziato è esterno al tenantTENANT_DISABLED,ENDPOINT_DISABLED- kill switchMCP_CONFIRMATION_REQUIRED- uno strumento MCP di scrittura/distruttivo necessita di conferma esplicita
Esempi
{ "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..." } }
Indicazioni per il client
Tratta 401 e 403 come problemi di configurazione o di permessi, non come errori ritentabili. Tratta 429 come ritentabile solo dopo il reset della finestra di rate limit. Usa le chiavi di idempotenza sulle scritture così da poter ritentare in sicurezza i guasti di trasporto. Vedi Idempotenza e Rate limit.