> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/es/api-web/solucion-de-problemas.md).

# Solución de problemas

Códigos de estado de Web API, formatos de respuesta de error, política de reintentos y soluciones comunes de solución de problemas.

## Códigos de estado

| Estado + código                                    | Descripción                                                                                                        | ¿Reintentar?                                                                            |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `200 OK`                                           | Resultado Realtime en el cuerpo de la respuesta                                                                    | –                                                                                       |
| `202 ACEPTADO`                                     | Trabajo asíncrono aceptado                                                                                         | –                                                                                       |
| `400 CUERPO_DE_SOLICITUD_MALFORMADO`               | El cuerpo de la solicitud no es JSON válido.                                                                       | No, corrige el formato del payload.                                                     |
| `400 ERROR_DE_VALIDACIÓN`                          | Uno o más campos no superaron la validación.                                                                       | No, corrige todas las entradas en `errors[]` antes de reenviar.                         |
| `401 NO_AUTORIZADO`                                | Error de autenticación (clave ausente, inválida, malformada o revocada). Sin cuerpo de respuesta para este estado. | No, corrige las credenciales.                                                           |
| `404 NO_ENCONTRADO`                                | Una ruta bajo `/search` no existe o asíncrono `request_id` no existe o ha expirado.                                | No                                                                                      |
| `405 MÉTODO_NO_PERMITIDO`                          | Se usó un método HTTP incorrecto (los endpoints requieren `POST`).                                                 | No                                                                                      |
| `408 TIEMPO_DE_ESPERA_AGOTADO`                     | `/scrape` solo. El scraper no respondió dentro de la ventana de espera del servidor                                | Sí, con backoff.                                                                        |
| `429 DEMASIADAS_SOLICITUDES`                       | Se superó el límite de tasa o la cuota. Consulta [Errores comunes](#id-1.-rate-limit-vs.-quota-exhaustion-429)     | <p><strong>Límite de tasa:</strong> sí, con backoff.<br><strong>Cuota:</strong> no.</p> |
| `500 SOLICITUD_FALLIDA_TRAS_DEMASIADOS_REINTENTOS` | Todos los motores upstream fallaron. No se cobró.                                                                  | Sí, con backoff.                                                                        |
| `500 ERROR_INTERNO_DEL_SERVIDOR`                   | Fallo inesperado del sistema                                                                                       | Sí, con backoff.                                                                        |
| `503 SERVICIO_NO_DISPONIBLE`                       | El servicio upstream no está disponible temporalmente                                                              | Sí, con backoff.                                                                        |
| `5xx`                                              | Otro fallo transitorio de upstream                                                                                 | Sí, hasta \~3 intentos con backoff.                                                     |

{% hint style="info" %}

* `Código` los valores son específicos de `/search` cuerpo de error estructurado (ver abajo). Los demás endpoints devuelven solo el número de estado.
* Pueden aparecer nuevos códigos a medida que la API crece: trata uno no reconocido como "un error de esta clase de estado".
  {% endhint %}

## Respuesta de error

`/search` los fallos usan un [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) documento de problema, servido como `application/problem+json`:

```json
{
  "status": 400,
  "title": "VALIDATION_ERROR",
  "detail": "1 request field is invalid; fix every entry in `errors` and resend.",
  "instance": "6285041d-b00d8d69959c4b36f50fb53b",
  "metadata": {
    "timestamp": 1788762578,
    "request_id": "1788875675880097469"
  },
  "errors": [
    {
      "pointer": "#/max_results",
      "detail": "Input should be less than or equal to 20"
    }
  ]
}
```

<table><thead><tr><th width="195">Campo</th><th>Descripción</th><th width="111">Tipo</th></tr></thead><tbody><tr><td><code>status</code></td><td>HTTP status code matching the response status line.</td><td>número</td></tr><tr><td><code>state</code></td><td>Presente en respuestas con fallo <code>500</code> (<code>"faulted"</code>). Las llamadas correctas devuelven <code>"done"</code>.</td><td>cadena</td></tr><tr><td><code>title</code></td><td>Código de error legible por máquina. Basa la lógica de la aplicación en este campo.</td><td>cadena</td></tr><tr><td><code>detail</code></td><td>Explicación legible por humanos del error. No hagas coincidir este texto en prosa.</td><td>cadena</td></tr><tr><td><code>instancia</code></td><td>Identificador de traza de la solicitud. Inclúyelo en las consultas al soporte.</td><td>cadena</td></tr><tr><td><code>metadata.request_id</code></td><td>Identificador de solicitud de 19 dígitos usado para seguimiento y soporte.</td><td>cadena</td></tr><tr><td><code>metadata.timestamp</code></td><td>Marca de tiempo Unix en segundos.</td><td>número</td></tr><tr><td><code>params</code></td><td>Todos los parámetros usados para la solicitud con los valores predeterminados aplicados. Presente en solicitudes validadas (p. ej., <code>500</code>), ausente en <code>400</code>.</td><td>objeto</td></tr><tr><td><code>errors[]</code></td><td>Lista de fallos de parámetros. Presente en <code>VALIDATION_ERROR</code> solo.</td><td>arreglo</td></tr><tr><td><code>errors[].pointer</code></td><td>JSON Pointer que identifica el campo rechazado (p. ej., <code>#/max_results</code>).</td><td>cadena</td></tr><tr><td><code>errors[].detail</code></td><td>Explicación de por qué se rechazó el campo específico.</td><td>cadena</td></tr></tbody></table>

## Reintentos

Reintentar `408`, `429` y `5xx` con backoff exponencial y jitter, limitado a \~3 intentos:

```python
import random, time, requests

RETRYABLE = {408, 429, 500, 502, 503, 504}

def call(url, payload, headers, attempts=3):
    for attempt in range(1, attempts + 1):
        try:
            resp = requests.post(url, json=payload, headers=headers, timeout=120)
        except requests.Timeout:
            if attempt == attempts:
                raise
            time.sleep(2**attempt + random.random())
            continue
        if resp.ok:
            return resp.json()
        if resp.status_code not in RETRYABLE or attempt == attempts:
            raise RuntimeError(f"{resp.status_code}: {resp.text[:200]}")
        time.sleep(2**attempt + random.random())  # jitter avoids lockstep retries
```

Ante un `429`, reduce la concurrencia en lugar de acortar el backoff. Reintentar más rápido contra un límite de tasa no lo solucionará.

## Errores comunes y soluciones

### **1. Límite de tasa vs. agotamiento de cuota (`429`)**

Tanto las violaciones del límite de tasa (superar la concurrencia de solicitudes por segundo) como el agotamiento de la cuota de la cuenta devuelven un HTTP `429 Demasiadas solicitudes` código.

**Solución:** Si un HTTP `429` persiste a lo largo de varios intentos con backoff que superan los 30 segundos, tu cuenta ha agotado su cuota mensual de solicitudes. Revisa tus límites de uso activos en el [Panel de Oxylabs](https://dashboard.oxylabs.io).

### **2. Timeouts en páginas con mucho JavaScript (`run_js: true`)**

Renderizado en navegador sin interfaz (`run_js: true`) o los sitios de destino complejos requieren mucho más tiempo de procesamiento que las recuperaciones HTML estándar, a menudo más que un timeout predeterminado típico del cliente (5–10 s).

**Solución:** Configura los timeouts del cliente en \~150 segundos. Para cualquier cosa que probablemente tarde mucho de todos modos, usa [Entrega asíncrona](https://developers.oxylabs.io/products/es/api-web/scrape/modos-de-entrega.md#single-job-delivery-async) en lugar de mantener la conexión abierta.

## Errores específicos de medios (`/scrape/media`)

`/media` y los trabajos de sus sub-endpoints pueden finalizar con HTTP `200` y `state: "done"`, pero no devuelven datos ni archivo con un error específico de medios en `results[0].metadata.statuses.video_download`:

{% code expandable="true" %}

```json
"statuses": {
    "video_download": {
        "code": 11206,
        "tag": "DOWNLOAD_FAILED_VIDEO_AGE_RESTRICTED", //"DOWNLOAD_FAILED_" prefix + status
        "details": "The video is age-restricted."
    }
}
```

{% endcode %}

{% hint style="info" %}
`11201`-`11211` aplican a `/media/youtube/metadata`, `/media/youtube/subtitles` y `/media/youtube/download` solo a los endpoints.
{% endhint %}

<table><thead><tr><th width="219">Error</th><th width="271">Descripción</th><th>Solución</th></tr></thead><tbody><tr><td><code>11201</code><br><code>VIDEO_DELETED</code></td><td>El video de YouTube fue eliminado.</td><td>Abre la URL en un navegador para confirmar que el video sigue allí. Reintentar el mismo video no ayudará.</td></tr><tr><td><code>11202</code><br><code>VIDEO_UNAVAILABLE</code></td><td>YouTube informa que el video no está disponible.</td><td>Abre el video en un navegador para comprobar que se reproduce. Si es así, contacta con soporte con el <code>request_id</code>.</td></tr><tr><td><code>11203</code><br><code>VIDEO_PRIVATE</code></td><td>El autor configuró el video como privado, así que solo él y los espectadores invitados pueden verlo.</td><td>Usa un video público.</td></tr><tr><td><code>11204</code><br><code>VIDEO_GEO_RESTRICTED</code></td><td>El video no está disponible en la región desde la que se ejecutó el trabajo.</td><td>Si necesitas este video, contacta con soporte con el <code>request_id</code>.</td></tr><tr><td><code>11205</code><br><code>VIDEO_LIVE</code></td><td>El video es una transmisión en vivo en curso.</td><td>Reintenta después de que termine la transmisión.</td></tr><tr><td><code>11206</code><br><code>VIDEO_AGE_RESTRICTED</code></td><td>El video tiene restricción de edad.</td><td>Los videos con restricción de edad no se pueden recuperar. Usa otro video.</td></tr><tr><td><code>11207</code><br><code>VIDEO_MEMBER_ONLY</code></td><td>El video solo está disponible para los miembros de pago del canal.</td><td>Los videos solo para miembros no se pueden recuperar. Usa otro video.</td></tr><tr><td><code>11208</code><br><code>VIDEO_PREMIUM_ONLY</code></td><td>El video requiere una suscripción a YouTube Premium.</td><td>Los videos solo de Premium no se pueden recuperar. Usa otro video.</td></tr><tr><td><code>11209</code><br><code>VIDEO_LIVE_OR_TOO_LONG</code></td><td>El video es una transmisión en vivo en curso o demasiado largo para descargar. <code>/media/youtube/download</code> solo.</td><td>Si el video está en vivo, reintenta después de que termine la transmisión. Se pueden descargar videos de hasta 12 horas.</td></tr><tr><td><code>11210</code><br><code>VIDEO_TOO_LONG</code></td><td>El video es demasiado largo para descargar. <code>/media/youtube/download</code> solo.</td><td>Se pueden descargar videos de hasta 12 horas. Usa un video más corto.</td></tr><tr><td><code>11211</code><br><code>VIDEO_SIGN_IN_REQUIRED</code></td><td>YouTube requiere iniciar sesión para ver el video. <code>/media/youtube/download</code> solo.</td><td>Los videos que requieren iniciar sesión no se pueden descargar. Usa otro video.</td></tr><tr><td><code>11301</code><br><code>MEDIA_UNAVAILABLE</code></td><td>El video fue eliminado, o la publicación a la que pertenecía ya no existe.</td><td>Abre la URL en un navegador para confirmar que el video sigue allí. Reintentar la misma URL no ayudará.</td></tr><tr><td><code>11302</code><br><code>MEDIA_PRIVATE</code></td><td>El video, o la cuenta que lo publicó, es privado. Solo se pueden descargar videos públicos.</td><td>Usa una URL de un video público.</td></tr><tr><td><code>11303</code><br><code>MEDIA_GEO_RESTRICTE</code>D</td><td>El video no está disponible en la región del trabajo. El <code>/media</code> endpoint no tiene <code>location</code> parámetro, así que la región no se puede cambiar en la solicitud.</td><td>Si necesitas este video, contacta con soporte con el <code>request_id</code>.</td></tr><tr><td><code>11304</code><br><code>MEDIA_UNSUPPORTED</code></td><td>No se encontró ningún video en la URL: una publicación de foto o diapositivas, una transmisión en vivo, una publicación sin video o un video demasiado largo o demasiado grande para descargar.</td><td>Comprueba que la URL coincida con uno de los formatos de URL aceptados y apunte a un único video grabado.</td></tr><tr><td>El video no llega a tu bucket</td><td><code>storage.url</code> no se valida. Se acepta un bucket o ruta mal escrito, y el trabajo se ejecuta y se factura, pero la carga falla.</td><td>Comprueba <code>storage.type</code> y <code>storage.url</code> antes de enviar. Para <code>s3_compatible</code> y <code>tos</code>, <code>storage.url</code> debe ser una URL completa con credenciales, p. ej., <code>https://key:secret@host/bucket/path</code>.</td></tr></tbody></table>

## Informar de un problema

Si persiste un problema de la API, captura el identificador de solicitud único del payload de respuesta antes de abrir un ticket con [Soporte técnico de Oxylabs](mailto:support@oxylabs.io).

* **Campo de respuesta:** `metadata.request_id` (por ejemplo, `"1788875675880097469"`)
* **Campo de error de la puerta de enlace:** `trace_id` (por ejemplo, `"d940ba3c-2109-4391-a292-9f2c0613a656"`)

Incluyendo el `request_id` o `trace_id` permite a nuestro soporte localizar de inmediato los trabajos, los datos de enrutamiento de nodos proxy y los códigos de respuesta upstream.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/es/api-web/solucion-de-problemas.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
