Operación segura
Decidí si corregir, esperar o reconciliar.
Una referencia única para interpretar error.code, conservar trazabilidad y evitar reintentos que dupliquen operaciones.
Contrato de respuesta
No reintentar401, 403 y validaciones hasta corregir la causa.
Esperar425 y 429 siguiendo Retry-After o el reset publicado.
ReconciliarEscrituras ambiguas e idempotency_indeterminate.
El código para la lógica; el mensaje para la persona.
Automatizá decisiones con el estado HTTP y error.code. Mostrá error.message sin reemplazarlo por un texto genérico y registrá el Request ID.
HTTP/1.1 403 Forbidden
X-Request-Id: req_01H...
{
"success": false,
"error": {
"code": "api_scope_required",
"message": "El token no tiene el scope requerido."
}
}
Catálogo operativo
Errores centrales y acción recomendada.
Los módulos pueden agregar códigos específicos, pero mantienen este mismo envelope y los permisos reales de PietroCal y DAV.
Autenticación y acceso
La solicitud no llegó al controlador o la credencial ya no puede usar esa operación.
unauthenticatedBearer ausente, inválido, vencido o revocado; también puede indicar una cuenta inactiva.
Acción
Renová o reemplazá la credencial y verificá que el usuario siga activo.
Reintento
No, hasta corregir la credencial.
api_scope_requiredLa credencial es válida, pero no incluye el scope exacto que exige el endpoint.
Acción
Solicitá el scope faltante. Recordá que write no incluye read.
Reintento
No, hasta emitir autorización suficiente.
api_method_not_enabledEse método todavía no está habilitado para consumidores Bearer.
Acción
Usá un método documentado o revisá Swagger y el changelog.
Reintento
No.
plan_feature_disabledEl plan vigente del titular ya no incluye acceso a la API.
Acción
Revisá el plan del titular; conservar un token anterior no evita este control.
Reintento
No, hasta habilitar la función.
Idempotencia y concurrencia
La clave protege una creación, pero el servidor necesita que el cliente preserve o reconcilie el comando original.
idempotency_conflictLa misma Idempotency-Key llegó con un método, endpoint o contenido diferente.
Acción
No reutilices la clave para otro comando. Conservá la clave original o generá otra para una operación realmente nueva.
Reintento
No con contenido diferente.
idempotency_indeterminatePietroCal no puede asegurar si una ejecución anterior produjo efectos.
Acción
Consultá el recurso o tu identificador externo antes de decidir si corresponde una nueva clave.
Reintento
No a ciegas; primero reconciliar.
idempotency_in_progressOtra solicitud mantiene el lock de esa misma clave.
Acción
Esperá Retry-After y repetí exactamente el mismo comando con la misma clave.
Reintento
Sí, con la misma clave.
api_idempotency_unavailableLa protección durable no está disponible y la escritura no fue ejecutada.
Acción
Esperá y repetí más tarde sin cambiar la clave del comando.
Reintento
Sí, cuando el servicio se recupere.
Límites y presupuestos
La credencial fue medida, pero alcanzó un límite por minuto, compartido o individual.
api_rate_limit_exceededEl token alcanzó el límite efectivo de solicitudes por minuto.
Acción
Esperá Retry-After y reducí concurrencia o frecuencia.
Reintento
Sí, después de Retry-After.
api_quota_exceededEl titular agotó la cuota mensual UTC compartida entre todas sus credenciales.
Acción
Esperá X-PietroCal-Quota-Reset o revisá el plan.
Reintento
Sí, después del reinicio.
api_token_budget_exceededLa credencial agotó su presupuesto mensual individual.
Acción
Esperá el reset o ajustá su presupuesto desde Integraciones y API sin superar el plan.
Reintento
Sí, después del reinicio.
Permisos, validación y estado del recurso
Los controladores conservan los códigos específicos de Calendarios, DAV, Contactos, Reservas y otros módulos.
código de permiso del recursoEl usuario autenticado no posee el permiso real sobre ese calendario, contacto, reserva o workspace.
Acción
No eleves privilegios desde el cliente: corregí el acceso del usuario o elegí un recurso autorizado.
Reintento
No, hasta cambiar permisos o recurso.
código de recurso no encontradoEl ID, URI o libreta no existe para ese propietario o dejó de estar disponible.
Acción
Refrescá el listado canónico y eliminá referencias locales obsoletas.
Reintento
No con la misma referencia.
código de conflicto o validaciónEl payload contradice el estado vigente, una regla temporal o el contrato del recurso.
Acción
Mostrá error.code y message al operador, actualizá el recurso y corregí el comando.
Reintento
Sólo después de corregir el estado o payload.
Matriz de reintentos
La ausencia de respuesta no significa ausencia de efecto.
La regla cambia según el método y la protección durable. Ante una escritura ambigua, priorizá reconciliar antes que repetir.
No aplica.
Las lecturas son seguras; limitá intentos y conservá X-Request-Id cuando exista.
La misma clave.
No generes una clave nueva entre intentos; podría duplicar el recurso.
Sin efecto.
Corregí token, scope, método, plan o permiso real.
No reutilizar para otro contenido.
La clave representa un único comando canónico.
Conservar para diagnóstico.
Consultá el recurso antes de crear una operación nueva.
La misma clave.
No aumentes concurrencia sobre el mismo comando.
La misma si era idempotente.
No hagas loops inmediatos; respetá rate, cuota y presupuesto.
La misma en creaciones idempotentes.
Sin protección, tratá la escritura como ambigua.
Diagnóstico y soporte
Un incidente útil no necesita exponer secretos.
Prepará un paquete mínimo que permita relacionar la solicitud con la actividad técnica de PietroCal.
- X-Request-Id exacto de la respuesta.
- Fecha y hora con zona horaria.
- Método HTTP y ruta; sanitizá parámetros sensibles.
- Código HTTP, error.code y error.message completos.
- Tipo y nombre de la credencial o su ID visible; nunca el Bearer.
- Si se usó Idempotency-Key y si la respuesta fue reproducida; no envíes cuerpos con datos privados.
- Resultado esperado, resultado observado y pasos mínimos para reproducir.
Nunca incluyasAuthorization Bearer, refresh token, Signing Secret, contraseñas, cookies o payloads con datos personales completos.
Referencia completa
Usá la fuente adecuada para cada decisión.
Swagger define la operación, las guías explican el flujo, el changelog informa cambios y esta página concentra recuperación y diagnóstico.