Errores
La API pública usa códigos de estado HTTP estables y un sobre de error legible por máquina. Quienes usan el SDK reciben un FabHubApiError tipado para cualquier respuesta que no sea 2xx.
Forma del error
{
"error": {
"code": "SCOPE_REQUIRED",
"message": "This credential is missing the items:write scope",
"request_id": "req_8f3a...",
"details": {}
}
}
request_id se incluye en la mayoría de las respuestas - cítalo en las solicitudes de soporte. details está presente en los errores de validación. Ramifica según el error.code estable, no según message.
Códigos de estado
| Estado | Significado |
|---|---|
400 | Petición inválida o error de validación |
401 | Credencial ausente, inválida, caducada o revocada |
403 | Scope faltante, restricción de plan o denegación por lista de IP permitidas |
404 | Recurso no encontrado |
409 | Conflicto de idempotencia (key reutilizada con un cuerpo diferente) |
429 | Límite de tasa superado |
500 | Error del servidor |
Códigos de error
BAD_REQUEST,UNAUTHORIZED,FORBIDDEN,NOT_FOUND,CONFLICT,RATE_LIMITED,INTERNAL_ERRORSCOPE_REQUIRED- a la credencial le falta un scope requeridoPLAN_REQUIRED- el plan del tenant no incluye esta capacidadOBJECT_ACCESS_DENIED- el objeto referenciado está fuera del tenantTENANT_DISABLED,ENDPOINT_DISABLED- interruptores de seguridadMCP_CONFIRMATION_REQUIRED- una herramienta de MCP de escritura/destructiva necesita confirmación explícita
Ejemplos
{ "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..." } }
Orientación para el cliente
Trata 401 y 403 como problemas de configuración o permisos, no como fallos reintentables. Trata 429 como reintentable solo después de que se restablezca la ventana del límite de tasa. Usa idempotency keys en las escrituras para poder reintentar de forma segura los fallos de transporte. Consulta Idempotencia y Límites de tasa.