> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Códigos de error

> Qué significa cada código de estado de Sorsa API, qué lo provoca y cómo resolverlo, del 400 al 500.

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:

```json theme={null}
{
  "message": "ApiKey required"
}
```

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

| Código | Tipo               | Significado                                               |
| :----- | :----------------- | :-------------------------------------------------------- |
| 200    | Correcto           | Solicitud completada correctamente                        |
| 400    | Error del cliente  | Solicitud incorrecta: faltan parámetros o no son válidos  |
| 401    | Error del cliente  | No autorizado: falló la autenticación                     |
| 403    | Error del cliente  | Prohibido: clave válida, pero sin acceso o saldo          |
| 404    | Error del cliente  | No encontrado: el recurso no existe o es privado          |
| 429    | Error del cliente  | Demasiadas solicitudes: se superó el límite de frecuencia |
| 500    | Error del servidor | Error interno del servicio                                |

## 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](https://docs.sorsa.io/es/api-reference-guide) 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](https://api.sorsa.io/overview/keys). Si tienes dudas, vuelve a copiarla desde allí. Consulta [Autenticación](https://docs.sorsa.io/es/authentication).

## 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](https://api.sorsa.io/overview). Si lo has agotado, recarga o cambia de plan en [Billing](https://api.sorsa.io/overview/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](https://docs.sorsa.io/es/rate-limits).

## 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](https://uptime.sorsa.io/status/v3).
* Si continúa, escribe a [contacts@sorsa.io](mailto:contacts@sorsa.io) o contacta por [Discord](https://discord.com/invite/uwAefKCj7X). 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**

```python theme={null}
import time
import requests

def sorsa_request(method, endpoint, api_key, params=None, json_body=None, max_attempts=3):
    """GET/POST data retrieval with bounded retries; max_attempts includes the first call."""
    method = method.upper()
    if method not in {"GET", "POST"}:
        raise ValueError("Use GET or POST")
    if max_attempts < 1:
        raise ValueError("max_attempts must be positive")
    url = f"https://api.sorsa.io/v3{endpoint}"

    for attempt in range(max_attempts):
        try:
            response = requests.request(
                method, url, headers={"ApiKey": api_key},
                params=params, json=json_body, timeout=30,
            )
        except (requests.Timeout, requests.ConnectionError):
            if attempt + 1 == max_attempts:
                raise
        else:
            if response.ok:
                return response.json()
            retryable = response.status_code == 429 or response.status_code >= 500
            if not retryable or attempt + 1 == max_attempts:
                try:
                    message = response.json().get("message", response.reason)
                except (ValueError, AttributeError):
                    message = response.reason
                raise requests.HTTPError(
                    f"HTTP {response.status_code}: {message}", response=response,
                )
        time.sleep(min(2 ** attempt, 8))

data = sorsa_request("GET", "/info", "YOUR_API_KEY", params={"username": "elonmusk"})
print(data["display_name"])
```

**JavaScript**

```javascript theme={null}
async function sorsaRequest(method, endpoint, apiKey, body = null, maxAttempts = 3) {
  method = method.toUpperCase();
  if (!["GET", "POST"].includes(method)) throw new Error("Use GET or POST");
  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
    throw new Error("maxAttempts must be a positive integer");
  }
  if (method === "GET" && body !== null) throw new Error("Use query parameters for GET");
  const url = `https://api.sorsa.io/v3${endpoint}`;
  const options = { method, headers: { ApiKey: apiKey } };
  if (body !== null) {
    options.headers["Content-Type"] = "application/json";
    options.body = JSON.stringify(body);
  }

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    let response;
    try {
      response = await fetch(url, { ...options, signal: AbortSignal.timeout(30000) });
    } catch (error) {
      if (attempt + 1 === maxAttempts) throw error;
      await new Promise((r) => setTimeout(r, Math.min(2 ** attempt, 8) * 1000));
      continue;
    }
    if (response.ok) return await response.json();
    const retryable = response.status === 429 || response.status >= 500;
    if (!retryable || attempt + 1 === maxAttempts) {
      let message = response.statusText;
      try { message = (await response.json()).message || message; } catch {}
      throw new Error(`HTTP ${response.status}: ${message}`);
    }
    await new Promise((r) => setTimeout(r, Math.min(2 ** attempt, 8) * 1000));
  }
}

const data = await sorsaRequest("GET", "/info?username=elonmusk", "YOUR_API_KEY");
console.log(data.display_name);
```

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

* [Límites de solicitudes](https://docs.sorsa.io/es/rate-limits): estrategias para respetar las 20 solicitudes por segundo.
* [Paginación](https://docs.sorsa.io/es/pagination): recuperación de grandes conjuntos de datos.
* [Referencia de la API](https://docs.sorsa.io/es/api-reference-guide): endpoints y esquemas de parámetros.