Skip to main content
Cuando una solicitud falla, Sorsa devuelve un código HTTP estándar y un cuerpo JSON con un campo message que describe el problema. Esta página explica los códigos, sus causas y cómo resolverlos.

Formato de las respuestas de error

Las respuestas de error comparten esta estructura:
El campo message contiene una descripción del problema. Revísalo primero al diagnosticar un error: a menudo indica directamente su causa.

Referencia rápida

400 Bad Request

No se pudo procesar la solicitud porque faltan parámetros o no son válidos. Causas habituales
  • Falta un parámetro obligatorio, como link, id, username o query.
  • Un parámetro tiene un tipo o formato incorrecto, como una cadena donde se espera un número.
  • El cuerpo JSON de una solicitud POST está vacío o mal formado.
Solución: consulta el endpoint en la referencia de la API y comprueba que todos los parámetros obligatorios estén presentes y tengan el formato correcto. En POST, utiliza Content-Type: application/json y un cuerpo JSON válido.

401 Unauthorized

La autenticación falló: la API no pudo identificar tu cuenta. Causas habituales
  • Falta el encabezado ApiKey.
  • El nombre del encabezado es incorrecto. Utiliza ApiKey; los nombres HTTP no distinguen mayúsculas de minúsculas, pero Api-Key y api_key son nombres diferentes.
  • La clave es incorrecta, se copió con espacios adicionales o fue eliminada.
Solución: confirma que envías ApiKey: your_key_here y que la clave sigue activa en el panel. Si tienes dudas, vuelve a copiarla desde allí. Consulta Autenticación.

403 Forbidden

La clave de API es válida, pero la solicitud fue rechazada. Causas habituales
  • Has agotado la cuota de solicitudes.
  • Tu suscripción ha caducado.
Solución: consulta el saldo mediante GET /key-usage-info o en el panel. Si lo has agotado, recarga o cambia de plan en Billing.

404 Not Found

El recurso solicitado no existe. Causas habituales
  • El usuario de X cambió su nombre, eliminó la cuenta o fue suspendido.
  • El autor eliminó la publicación.
  • La cuenta o la publicación es privada o está protegida. Sorsa solo accede a datos públicos.
  • La URL del endpoint es incorrecta.
Solución: confirma que el usuario o la publicación siguen existiendo y son públicos en X. Los IDs de usuario permanecen estables aunque cambie el nombre. Si conservas el ID, utiliza /id-to-username/{user_id} para obtener el nombre actual o envía user_id a los endpoints que lo admitan.

429 Too Many Requests

Has superado el límite de 20 solicitudes por segundo. Causas habituales
  • Envío de solicitudes en un bucle sin pausas.
  • Varios procesos paralelos que comparten una clave de API.
Solución: añade una pausa entre solicitudes (50 ms regulan un único proceso secuencial; los procesos con una clave compartida requieren coordinación) o reintentos con una espera de un segundo. Consulta estrategias y ejemplos en Límites de solicitudes.

500 Internal Server Error

Se produjo un error en nuestro servicio. Qué hacer
  • Reintenta tras 1 o 2 segundos. Los errores 500 transitorios suelen resolverse solos.
  • Si persiste o afecta a varios endpoints, consulta los incidentes en la página de estado.
  • Si continúa, escribe a [email protected] o contacta por Discord. Incluye la URL del endpoint, el cuerpo de la solicitud y la hora aproximada. Elimina claves de API y encabezados de autorización del material de diagnóstico.

Gestión de errores en el código

Una integración robusta gestiona los códigos de error en lugar de fallar ante una respuesta inesperada. Estos patrones se pueden reutilizar en Python y JavaScript. Python
JavaScript
Los ejemplos reintentan tiempos de espera agotados, fallos de conexión y respuestas 429 y 5xx, con un máximo predeterminado de tres intentos. Los demás errores HTTP fallan inmediatamente. Una respuesta correcta con JSON no válido también falla para permitir su inspección. Utiliza Node.js 18 o posterior para JavaScript e instala requests antes de ejecutar Python.

Próximos pasos