Errores
La Partner API usa códigos de estado HTTP estándar y cuerpos de respuesta JSON para explicar por qué falló una solicitud.
Estructura de las respuestas de error
La mayoría de los errores de la API devuelven un cuerpo JSON con un mensaje y, cuando están disponibles, detalles estructurados.
{
"success": false,
"message": "Request body.members[0].member_id is required"
}
Algunos endpoints específicos de un dominio devuelven un estado y un motivo explícitos. Por ejemplo, los errores de control de acceso incluyen campos como reason, door_id, facility_id y event_id.
{
"status": "failed",
"reason": "device_offline",
"door_id": "00000000000000000000000000000007",
"facility_id": "550e8400-e29b-41d4-a716-446655440000",
"event_id": "00000000-0000-0000-0000-000000000045"
}
Códigos de estado
400 Bad Request
La solicitud tiene un formato incorrecto o le faltan campos obligatorios. Corrige la solicitud antes de reintentar.
401 Unauthorized
Falló la autenticación. Comprueba que usas HTTP Basic Auth con tu clave secreta de API como nombre de usuario y una contraseña vacía.
403 Forbidden
La clave es válida, pero la operación no está permitida. Las causas habituales son usar una clave de solo lectura para una operación de escritura o intentar acceder a una instalación donde tu integración no está habilitada.
404 Not Found
No se encontró el recurso solicitado o no está disponible para tu integración.
409 Conflict
La solicitud entra en conflicto con el estado actual del recurso. En el control de acceso, puede deberse, por ejemplo, a que un controlador de puertas y portones está en modo de mantenimiento.
422 Unprocessable Entity
La solicitud es un JSON válido, pero no supera la validación semántica. Corrige los datos antes de reintentar.
429 Too Many Requests
La integración superó el límite de frecuencia documentado. Reintenta con retroceso exponencial.
500 Internal Server Error
El Performance Hub no pudo completar la solicitud debido a un error interno. Reintenta con retroceso. Si el problema continúa, comunícate con soporte e indica el endpoint, la marca de tiempo y el cuerpo de la respuesta.
503 Service Unavailable
Un servicio o dispositivo del que depende la operación no está disponible. En los desbloqueos de controladores de puertas y portones, puede significar que el controlador está desconectado.
504 Gateway Timeout
Se agotó el tiempo de espera de la operación. En los desbloqueos de controladores de puertas y portones, significa que el desbloqueo no se confirmó antes de que terminara el tiempo de espera.
Errores de Access Time Windows
La validación de las ventanas falla antes de que se escriba la instantánea no válida. Las causas habituales que no admiten reintento son:
- Falta
access_time_windows_revisioncuandoaccess_time_windowsestá presente. - Valores de época como cadena, de coma flotante o que probablemente estén en milisegundos.
- Una zona horaria IANA no válida, un intervalo invertido, un
external_idduplicado, bloques semanales superpuestos o un bloque nocturno que no se dividió. - Un valor fuera de los límites documentados de cantidad, longitud o duración.
Una revisión repetida con contenido normalizado diferente genera un 409 Conflict. Concilia con el último estado autorizado y asigna una revisión más reciente; no sigas reintentando el par en conflicto. Una revisión anterior se notifica como una instantánea omitida por obsoleta, en lugar de permitir que sobrescriba un estado más reciente. Un scope_key desconocido o sin asignar deniega la autorización y debe tratarse como una alerta de configuración.
Si se agota el tiempo de espera de la entrega o se recibe un 5xx transitorio, reintenta exactamente la misma instantánea normalizada con la misma revisión. Si falló la consulta a la fuente de origen, omite por completo el campo de ventanas; nunca lo sustituyas por una matriz vacía.
Pautas de reintento
Reintenta estos errores con un retroceso exponencial acotado:
429500502503504
No reintentes estos errores a ciegas:
400401403404409422
En el control de acceso, trata siempre las respuestas de tiempo de espera agotado y de dispositivo desconectado como desbloqueos fallidos, a menos que tus propias reglas de acceso y procesos de seguridad indiquen lo contrario.
Datos que debes incluir al solicitar soporte
Cuando te comuniques con soporte, incluye:
- Endpoint y método HTTP.
- Marca de tiempo y zona horaria.
- ID de la clave de socio, no la clave secreta.
- Identificador de instalación usado.
- ID del registro de origen en tu sistema.
- Estado y cuerpo de la respuesta.
event_idocommand_id, si están disponibles.