> 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/api-reference/es/errores-y-codigos-de-estado.md).

# Errores y códigos de estado

Especificación técnica de los códigos de estado HTTP, los documentos de problema RFC 9457, la clasificación de errores y la lógica de reintento en producción para la Web API de Oxylabs.

### Código de estado y matriz de reintentos

La lógica de reintentos debe estar estrictamente condicionada a los códigos de estado HTTP de la respuesta. Reintentar errores de cliente no reintentables (`400`, `401`, `403`, `404`) provoca fallos idénticos y carga innecesaria en la API.

<table><thead><tr><th width="207">Estado + código</th><th width="183">Título RFC 9457</th><th>Descripción</th><th width="117">¿Se puede reintentar?</th></tr></thead><tbody><tr><td><code>200 OK</code></td><td>—</td><td>Llamada Realtime correcta. Ejecución completada; procesa el cuerpo de la respuesta.</td><td>No</td></tr><tr><td><code>202 Aceptado</code></td><td>—</td><td>Trabajo asíncrono aceptado. Trabajo en cola; recupéralo mediante <code>metadata.request_id</code>.</td><td>No</td></tr><tr><td><code>400 Solicitud incorrecta</code></td><td><code>INVALID_BODY_PROPERTY</code>, <code>MALFORMED_JSON</code></td><td>Carga útil con validación fallida o mal formada. Corrige los parámetros en <code>errors[]</code> antes de reenviar.</td><td>No</td></tr><tr><td><code>401 No autorizado</code></td><td>— <em>(Cuerpo vacío)</em></td><td>Clave de API inválida, ausente o revocada. Verifica el formato del token Bearer y la clave de instancia del panel.</td><td>No</td></tr><tr><td><code>403 Prohibido</code></td><td>—</td><td>Restricción de permisos. La cuenta no tiene acceso a la ruta o fuente de destino.</td><td>No</td></tr><tr><td><code>404 No encontrado</code></td><td><code>NOT_FOUND</code></td><td>Ruta o ID de trabajo no válido o expirado. Comprueba la ruta del endpoint o el handle de la solicitud asíncrona.</td><td>No</td></tr><tr><td><code>405 Método no permitido</code></td><td><code>METHOD_NOT_ALLOWED</code></td><td>Se usó un método distinto de <code>POST</code> . Cambia el método de la solicitud HTTP a <code>POST</code>.</td><td>No</td></tr><tr><td><code>408 Tiempo de espera de la solicitud agotado</code></td><td>—</td><td>Tiempo de espera agotado del scraping Realtime. Reintenta la solicitud con backoff exponencial.</td><td>Sí</td></tr><tr><td><code>413 Carga útil demasiado grande</code></td><td>—</td><td>Se superó el tamaño de la carga útil o del lote. Reduce el tamaño de la carga útil o el número de objetivos por lote.</td><td>No</td></tr><tr><td><code>429 Demasiadas solicitudes</code></td><td>—</td><td>Se agotó el límite de concurrencia o la cuota. Reduce la concurrencia y aplica backoff con jitter. Alerta al operador si persiste.</td><td><p>Límite de tasa: Sí</p><p>Cuota: No</p></td></tr><tr><td><code>500 Error interno</code></td><td><code>REQUEST_FAILED_AFTER_TOO_MANY_RETRIES</code>, <code>INTERNAL_ERROR</code></td><td>Fallo aguas arriba o scraping con error. Los scrapes con error no se cobran. Reintenta con backoff.</td><td>Sí</td></tr><tr><td><code>503 Servicio no disponible</code></td><td><code>SERVICE_UNAVAILABLE</code></td><td>El servicio está temporalmente caído. Reintenta con backoff.</td><td>Sí</td></tr></tbody></table>

### Documentos de problema RFC 9457

Cuando ocurre un error HTTP, la Web API devuelve un [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) documento de problema servido como `application/problem+json`.

{% hint style="info" %}
`401 No autorizado` Excepción: HTTP `401` las respuestas de estado llevan un cuerpo vacío. El propio código de estado HTTP representa el estado completo de fallo de autenticación.
{% endhint %}

#### 1. Propiedad de cuerpo no válida (`400 Solicitud incorrecta`)

No válido `storage.url` devuelve `VALIDATION_ERROR` con `errors[].pointer` establecido en `#/storage/url`. La solicitud no se crea.

```json
{
  "status": 400,
  "title": "INVALID_BODY_PROPERTY",
  "detail": "A body property has an invalid value.",
  "instance": "6ad5c6df-4ef52bbe9bd1519f8dbfc4ae",
  "errors": [
    {
      "detail": "Must be one of: gcs, s3, s3_gzip, s3_compatible, tos.",
      "pointer": "#/storage/type"
    }
  ]
}
```

#### 2. Error de scraping con fallo (`500 Error interno`)

Si un scrape falla después de todos los reintentos, `POST /v1/scrape` devuelve un HTTP `500` estado con `state: "faulted"`. Los scrapes con fallo no consumen cuota de la cuenta.

```json
{
  "status": 500,
  "state": "faulted",
  "title": "REQUEST_FAILED_AFTER_TOO_MANY_RETRIES",
  "detail": "The request failed after the maximum number of retries. You can try again at no extra cost, as we don't charge you for faulted scrapes.",
  "instance": "6ad5c789-3cb04e139b34a1eaee352bae",
  "params": {
    "url": "https://oxyasdasdasdasdlabsghrehaerhaerh.io",
    "output": ["html"],
    "json": { "schema": null, "prompt": null },
    "location": null,
    "device": "desktop",
    "run_js": null
  },
  "metadata": {
    "timestamp": 1792395145,
    "request_id": "7517850129655711745"
  }
}
```

### Desglose del esquema de respuesta

<table><thead><tr><th width="192">Ruta del campo</th><th width="99.5">Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td><code>status</code></td><td>entero</td><td>Código de estado HTTP.</td></tr><tr><td><code>state</code></td><td>cadena</td><td>Presente en respuestas de scrape con fallo ( <code>500</code> "faulted"<code>"faulted"</code>). Las llamadas correctas devuelven <code>"done"</code>.</td></tr><tr><td><code>title</code></td><td>cadena</td><td>Código de error legible por máquina. Basa la lógica de errores de la aplicación en este valor.</td></tr><tr><td><code>detail</code></td><td>cadena</td><td>Mensaje de error legible por humanos. No analices la prosa para la lógica de ramificación del programa.</td></tr><tr><td><code>instance</code></td><td>cadena</td><td>Identificador único de rastreo para depuración interna y escalado al soporte.</td></tr><tr><td><code>metadata.request_id</code></td><td>cadena</td><td>Identificador de seguimiento de 19 dígitos para facturación y tickets de soporte.</td></tr><tr><td><code>metadata.timestamp</code></td><td>entero</td><td>Marca de tiempo Unix en segundos.</td></tr><tr><td><code>errors[]</code></td><td>array</td><td>Presente en errores de validación de solicitudes. Contiene objetos de fallo a nivel de campo.</td></tr><tr><td><code>errors[].pointer</code></td><td>cadena</td><td>JSON Pointer que identifica el campo de solicitud no válido (por ejemplo, <code>#/storage/type</code>).</td></tr><tr><td><code>errors[].detail</code></td><td>cadena</td><td>Motivo detallado del fallo para el puntero de campo especificado.</td></tr></tbody></table>

### Referencia del código de error (`title`)

El enrutamiento programático de errores debe evaluar el `title` atributo:

<table><thead><tr><th>"title" Code</th><th width="122">Estado HTTP</th><th>Descripción</th></tr></thead><tbody><tr><td><code>MALFORMED_JSON</code></td><td><code>400</code></td><td>El cuerpo de la solicitud no es JSON válido.</td></tr><tr><td><code>INVALID_BODY_PROPERTY</code></td><td><code>400</code></td><td>Una propiedad del cuerpo de la solicitud tiene un valor no válido.</td></tr><tr><td><code>NOT_FOUND</code></td><td><code>404</code></td><td>Ruta de endpoint no válida o subrecurso de endpoint sin asignar.</td></tr><tr><td><code>METHOD_NOT_ALLOWED</code></td><td><code>405</code></td><td>Se usó un método HTTP incorrecto (los endpoints de la Web API requieren <code>POST</code>).</td></tr><tr><td><code>REQUEST_FAILED_AFTER_TOO_MANY_RETRIES</code></td><td><code>500</code></td><td>El scrape falló después del número máximo de reintentos. Sin cargo.</td></tr><tr><td><code>INTERNAL_ERROR</code></td><td><code>500</code></td><td>Error de procesamiento interno.</td></tr><tr><td><code>SERVICE_UNAVAILABLE</code></td><td><code>503</code></td><td>Interrupción temporal del servicio de backend.</td></tr></tbody></table>

### Errores específicos de medios

Devueltos por `POST /v1/async/scrape/media` y sus subendpoints cuando el video no se puede descargar.

<table><thead><tr><th width="74.03125">Código</th><th width="216.372304199773">Estado</th><th>Descripción</th></tr></thead><tbody><tr><td><code>11201</code></td><td><code>VIDEO_DELETED</code></td><td>El video ha sido eliminado.</td></tr><tr><td><code>11202</code></td><td><code>VIDEO_UNAVAILABLE</code></td><td>El video no está disponible.</td></tr><tr><td><code>11203</code></td><td><code>VIDEO_PRIVATE</code></td><td>El video está configurado como privado por el autor y solo él y las personas invitadas explícitamente pueden verlo.</td></tr><tr><td><code>11204</code></td><td><code>VIDEO_GEO_RESTRICTED</code></td><td>El video tiene restricción geográfica.</td></tr><tr><td><code>11205</code></td><td><code>VIDEO_LIVE</code></td><td>El video está en directo ahora.</td></tr><tr><td><code>11206</code></td><td><code>VIDEO_AGE_RESTRICTED</code></td><td>El video tiene restricción de edad.</td></tr><tr><td><code>11207</code></td><td><code>VIDEO_MEMBER_ONLY</code></td><td>El video es solo para miembros del canal, y los espectadores deben pagar la cuota mensual de suscripción.</td></tr><tr><td><code>11208</code></td><td><code>VIDEO_PREMIUM_ONLY</code></td><td>El video requiere la suscripción a YouTube Premium.</td></tr><tr><td><code>11209</code></td><td><code>VIDEO_LIVE_OR_TOO_LONG</code></td><td>El video está en directo o es demasiado largo para descargarse.</td></tr><tr><td><code>11210</code></td><td><code>VIDEO_TOO_LONG</code></td><td>El video es demasiado largo para descargarse.</td></tr><tr><td><code>11211</code></td><td><code>VIDEO_SIGN_IN_REQUIRED</code></td><td>Se requiere iniciar sesión.</td></tr><tr><td><code>11301</code></td><td><code>MEDIA_UNAVAILABLE</code></td><td>El video fue eliminado o ya no existe</td></tr><tr><td><code>11302</code></td><td><code>MEDIA_PRIVATE</code></td><td>El video o la cuenta es privada</td></tr><tr><td><code>11303</code></td><td><code>MEDIA_GEO_RESTRICTED</code></td><td>El video no está disponible en la región del trabajo</td></tr><tr><td><code>11304</code></td><td><code>MEDIA_UNSUPPORTED</code></td><td>No es un video descargable: una foto, presentación de diapositivas, transmisión en directo o publicación sin formatos de video, o un video demasiado largo o grande para descargarse</td></tr></tbody></table>


---

# 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/api-reference/es/errores-y-codigos-de-estado.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.