Errores y Soporte

La API de Platica utiliza códigos de estado HTTP estándar para indicar el éxito o fracaso de las solicitudes. Esta sección describe los formatos de error, códigos comunes y cómo obtener ayuda.

Formato de Errores

Todas las respuestas de error siguen un formato JSON consistente:

{
  "code": 404,
  "error": "Not Found - El recurso no existe",
  "details": "Agent not found"
}

Códigos de Error Comunes

{
  "code": 400,
  "error": "Bad Request - Validation error",
  "details": "El campo 'name' es requerido"
}

{
  "code": 401,
  "error": "Unauthorized - Invalid API key",
  "details": "La API key proporcionada no es válida"
}

{
  "code": 403,
  "error": "Forbidden - Access denied",
  "details": "No tienes permisos para acceder a este workspace"
}

{
  "code": 404,
  "error": "Not Found - Resource not found",
  "details": "Agent not found"
}

{
  "code": 429,
  "error": "Too Many Requests - Rate limit exceeded",
  "details": "Has excedido el límite de 30 peticiones por segundo"
}

Errores de validación

Cuando varios campos fallan, details es un arreglo. Cada elemento identifica la ruta y la regla incumplida:

{
  "code": 400,
  "error": "Bad Request - The request has validation errors",
  "details": [
    {
      "path": ["attachments"],
      "message": "Array must contain at most 10 element(s)"
    }
  ]
}

En POST /v1/chat, delay y scheduleAt son mutuamente exclusivos. Si envías ambos, la API responde 400 y señala los campos en details.

Corrige todos los elementos de details antes de repetir la solicitud.

Rate Limiting

La API tiene límites de peticiones para garantizar un servicio estable para todos los usuarios.

Headers de Rate Limiting

Las respuestas incluyen headers que te ayudan a monitorear tu uso:

Mejores Prácticas

Para manejar errores de forma efectiva:

1. Siempre verifica el código de estado antes de procesar la respuesta
2. Implementa reintentos con backoff exponencial para errores 502, 503 y 504
3. No reintentes errores 4xx sin corregir la solicitud
4. Monitorea los headers de rate limiting para evitar exceder límites
5. Registra los errores con el campo details para debugging

Soporte Técnico

Si necesitas ayuda con la integración o tienes preguntas: