> 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/resolucion-de-problemas.md).

# Resolución de problemas

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

## Códigos de estado

| Estado + código                             | Descripción                                                                                                            | ¿Reintentar?                                                                            |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `200 OK`                                    | Resultado de Realtime en el cuerpo de la respuesta                                                                     | –                                                                                       |
| `202 ACCEPTED`                              | Trabajo asíncrono aceptado                                                                                             | –                                                                                       |
| `400 MALFORMED_REQUEST_BODY`                | El cuerpo de la solicitud no es JSON válido                                                                            | No, corrige el formato del payload.                                                     |
| `400 VALIDATION_ERROR`                      | Uno o más campos no superaron la validación.                                                                           | No, corrige todas las entradas en `errors[]` antes de reenviar.                         |
| `401 UNAUTHORIZED`                          | Error de autenticación (clave faltante, inválida, malformada o revocada). No hay cuerpo de respuesta para este estado. | No, corrige las credenciales.                                                           |
| `404 NOT_FOUND`                             | Una ruta bajo `/search` no existe o asíncrono `request_id` no existe o ha expirado.                                    | No                                                                                      |
| `405 METHOD_NOT_ALLOWED`                    | Se usó un método HTTP incorrecto (los endpoints requieren `POST`).                                                     | No                                                                                      |
| `408 REQUEST_TIMEOUT`                       | `/scrape` solo. El scraper no respondió dentro de la ventana de espera del servidor                                    | Sí, con backoff.                                                                        |
| `429 TOO_MANY_REQUESTS`                     | 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 REQUEST_FAILED_AFTER_TOO_MANY_RETRIES` | Fallaron todos los motores upstream. No se cobró.                                                                      | Sí, con backoff.                                                                        |
| `500 INTERNAL_SERVER_ERROR`                 | Fallo inesperado del sistema                                                                                           | Sí, con backoff.                                                                        |
| `503 SERVICE_UNAVAILABLE`                   | Servicio upstream temporalmente no disponible                                                                          | Sí, con backoff.                                                                        |
| `5xx`                                       | Otro fallo transitorio upstream                                                                                        | Sí, hasta \~3 intentos con backoff.                                                     |

{% hint style="info" %}

* `Código` los valores son específicos de `/search` el 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 campo de solicitud no es válido; corrige cada entrada en `errors` y vuelve a enviarla.",
  "instance": "6285041d-b00d8d69959c4b36f50fb53b",
  "metadata": {
    "timestamp": 1788762578,
    "request_id": "1788875675880097469"
  },
  "errors": [
    {
      "pointer": "#/max_results",
      "detail": "La entrada debe ser menor o igual que 20"
    }
  ]
}
```

<table><thead><tr><th width="195">Campo</th><th>Descripción</th><th width="111">Tipo</th></tr></thead><tbody><tr><td><code>estado</code></td><td>Código de estado HTTP que coincide con la línea de estado de la respuesta.</td><td>número</td></tr><tr><td><code>state</code></td><td>Presente en respuestas con error ( <code>500</code> respuestas (<code>"faulted"</code>). Las llamadas exitosas 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 la uses para comparar con este texto en prosa.</td><td>cadena</td></tr><tr><td><code>instance</code></td><td>Identificador de traza para la solicitud. Inclúyelo en las consultas de 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 solo 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

Reintento `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
```

Si persiste `429`, reduce la concurrencia en lugar de acortar el backoff. Reintentar más rápido ante un límite de tasa no lo resolverá.

## Errores comunes y soluciones

### **1. Límite de tasa frente a 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 código HTTP `429 Too Many Requests` código.

**Solución:** Si un HTTP `429` persiste durante varios intentos de backoff que abarcan más de 30 segundos, tu cuenta ha agotado su cuota mensual de solicitudes. Revisa tus límites de uso activos en el [Dashboard de Oxylabs](https://dashboard.oxylabs.io).

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

Renderizado de Headless Browser (`run_js: true`) o los sitios objetivo complejos requieren significativamente más tiempo de procesamiento que las solicitudes HTML estándar, a menudo más que un tiempo de espera predeterminado típico del cliente (5–10 s).

**Solución:** Configura los tiempos de espera del cliente en \~150 segundos. Para cualquier cosa que probablemente tarde mucho de todos modos, usa [Entrega asíncrona](/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 sus trabajos de sub-endpoint 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` se aplica a `/media/youtube/metadata`, `/media/youtube/subtitles` y `/media/youtube/download` solo en 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 ahí. 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 lo hace, contacta con soporte con el identificador del trabajo <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 identificador del trabajo <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>Los videos solo para miembros no se pueden recuperar. Usa otro video.</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 para 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 es demasiado largo para descargar. <code>/media/youtube/download</code> solo.</td><td>Si el video está en vivo, vuelve a intentarlo después de que termine la transmisión. Se pueden descargar videos de hasta 12 horas de duración.</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 de duración. 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 ahí. 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 privada. 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>ubicación</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 identificador del trabajo <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 presentación, 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 aceptados y apunte a un solo video grabado.</td></tr><tr><td>El video no llega a tu bucket</td><td><code>storage.url</code> no se valida. Un bucket o una ruta mal escritos se aceptan, y el trabajo se ejecuta y se factura, pero la subida 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 un problema de API persiste, captura el identificador único de solicitud 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` (p. ej., `"1788875675880097469"`)
* **Campo de error del gateway:** `trace_id` (p. ej., `"d940ba3c-2109-4391-a292-9f2c0613a656"`)

Incluir 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/resolucion-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.