Erreurs

L'API publique utilise des codes de statut HTTP stables et une enveloppe d'erreur exploitable par machine. Les appelants du SDK reçoivent une erreur typée FabHubApiError pour toute réponse autre que 2xx.

Forme de l'erreur

{
  "error": {
    "code": "SCOPE_REQUIRED",
    "message": "This credential is missing the items:write scope",
    "request_id": "req_8f3a...",
    "details": {}
  }
}

request_id est inclus dans la plupart des réponses - citez-le dans les demandes d'assistance. details est présent pour les erreurs de validation. Branchez-vous sur le error.code stable, pas sur message.

Codes de statut

Codes d'erreur

• BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, RATE_LIMITED, INTERNAL_ERROR
• SCOPE_REQUIRED - l'identifiant ne dispose pas d'un scope requis
• PLAN_REQUIRED - le plan du tenant n'inclut pas cette capacité
• OBJECT_ACCESS_DENIED - l'objet référencé est en dehors du tenant
• TENANT_DISABLED, ENDPOINT_DISABLED - interrupteurs d'arrêt
• MCP_CONFIRMATION_REQUIRED - un outil MCP en écriture/destructif nécessite une confirmation explicite

Exemples

{ "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..." } }

Recommandations pour le client

Traitez 401 et 403 comme des problèmes de configuration ou de permission, et non comme des échecs réessayables. Ne traitez 429 comme réessayable qu'après la réinitialisation de la fenêtre de limitation de débit. Utilisez des clés d'idempotence sur les écritures afin de pouvoir réessayer en toute sécurité les échecs de transport. Voir Idempotence et Limites de débit.