> 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/pt-br/api-da-web/solucao-de-problemas.md).

# Solução de problemas

Códigos de status da Web API, formatos de resposta de erro, política de retentativa e soluções comuns de troubleshooting.

## Códigos de status

| Status + Código                             | Descrição                                                                                                   | Tentar novamente?                                                                        |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `200 OK`                                    | Resultado Realtime no corpo da resposta                                                                     | –                                                                                        |
| `202 ACCEPTED`                              | Job assíncrono aceito                                                                                       | –                                                                                        |
| `400 MALFORMED_REQUEST_BODY`                | O corpo da requisição não é um JSON válido                                                                  | Não, corrija a formatação do payload.                                                    |
| `400 VALIDATION_ERROR`                      | Um ou mais campos falharam na validação.                                                                    | Não, corrija todas as entradas em `errors[]` antes de reenviar.                          |
| `401 UNAUTHORIZED`                          | Erro de autenticação (chave ausente, inválida, malformada ou revogada). Sem corpo de resposta neste status. | Não, corrija as credenciais.                                                             |
| `404 NOT_FOUND`                             | Um caminho em `/search` não existe ou é assíncrono `request_id` não existe ou expirou.                      | Não                                                                                      |
| `405 METHOD_NOT_ALLOWED`                    | Método HTTP incorreto usado (os endpoints exigem `POST`).                                                   | Não                                                                                      |
| `408 REQUEST_TIMEOUT`                       | `/scrape` apenas. O scraper não respondeu dentro da janela de espera do servidor                            | Sim, com backoff.                                                                        |
| `429 TOO_MANY_REQUESTS`                     | Limite de taxa ou cota excedidos. Veja [Erros comuns](#id-1.-rate-limit-vs.-quota-exhaustion-429)           | <p><strong>Limite de taxa:</strong> sim, com backoff.<br><strong>Cota:</strong> não.</p> |
| `500 REQUEST_FAILED_AFTER_TOO_MANY_RETRIES` | Todos os mecanismos upstream falharam. Não cobrado.                                                         | Sim, com backoff.                                                                        |
| `500 INTERNAL_SERVER_ERROR`                 | Falha inesperada do sistema                                                                                 | Sim, com backoff.                                                                        |
| `503 SERVICE_UNAVAILABLE`                   | Serviço upstream temporariamente indisponível                                                               | Sim, com backoff.                                                                        |
| `5xx`                                       | Outra falha transitória upstream                                                                            | Sim, até \~3 tentativas com backoff.                                                     |

{% hint style="info" %}

* `Código` os valores são específicos para `/search` corpo de erro estruturado (veja abaixo). Outros endpoints retornam apenas o número do status.
* Novos códigos podem aparecer conforme a API cresce: trate um não reconhecido como "um erro desta classe de status."
  {% endhint %}

## Resposta de erro

`/search` as falhas usam um [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 requisição é inválido; corrija cada entrada em `errors` e reenvie.",
  "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>Descrição</th><th width="111">Tipo</th></tr></thead><tbody><tr><td><code>status</code></td><td>Código de status HTTP correspondente à linha de status da resposta.</td><td>número</td></tr><tr><td><code>state</code></td><td>Presente em <code>500</code> respostas com falha (<code>"faulted"</code>). Chamadas bem-sucedidas retornam <code>"done"</code>.</td><td>cadeia de caracteres</td></tr><tr><td><code>title</code></td><td>Código de erro legível por máquina. Direcione a lógica da aplicação com base neste campo.</td><td>cadeia de caracteres</td></tr><tr><td><code>detail</code></td><td>Explicação legível por humanos do erro. Não compare com este texto em prosa.</td><td>cadeia de caracteres</td></tr><tr><td><code>instance</code></td><td>Identificador de rastreamento da requisição. Inclua em consultas de suporte.</td><td>cadeia de caracteres</td></tr><tr><td><code>metadata.request_id</code></td><td>Identificador de requisição de 19 dígitos usado para rastreamento e suporte.</td><td>cadeia de caracteres</td></tr><tr><td><code>metadata.timestamp</code></td><td>Timestamp Unix epoch em segundos.</td><td>número</td></tr><tr><td><code>params</code></td><td>Todos os parâmetros usados na requisição com padrões aplicados. Presente em requisições validadas (por exemplo, <code>500</code>), ausente em <code>400</code>.</td><td>objeto</td></tr><tr><td><code>errors[]</code></td><td>Lista de falhas de parâmetros. Presente em <code>VALIDATION_ERROR</code> apenas.</td><td>vetor</td></tr><tr><td><code>errors[].pointer</code></td><td>JSON Pointer que identifica o campo rejeitado (por exemplo, <code>#/max_results</code>).</td><td>cadeia de caracteres</td></tr><tr><td><code>errors[].detail</code></td><td>Explicação de por que o campo específico foi rejeitado.</td><td>cadeia de caracteres</td></tr></tbody></table>

## Novas tentativas

Nova tentativa `408`, `429`, e `5xx` com backoff exponencial e jitter, limitado a \~3 tentativas:

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

Em caso de `429`, reduza a concorrência em vez de encurtar o backoff. Tentar novamente mais rápido diante de um limite de taxa não vai resolver.

## Erros comuns e soluções

### **1. Limite de taxa vs. esgotamento da cota (`429`)**

Tanto violações de limite de taxa (exceder a concorrência de requisições por segundo) quanto esgotamento da cota da conta retornam um HTTP `429 Too Many Requests` code.

**Solução:** Se um HTTP `429` persistir por várias tentativas com backoff ao longo de mais de 30 segundos, sua conta esgotou a cota mensal de requisições. Inspecione seus limites de uso ativos no [Painel da Oxylabs](https://dashboard.oxylabs.io).

### **2. Timeouts em páginas pesadas em JavaScript (`run_js: true`)**

Renderização em Headless Browser (`run_js: true`) ou sites-alvo complexos exigem significativamente mais tempo de processamento do que buscas HTML padrão, muitas vezes mais do que um timeout padrão típico do cliente (5–10s).

**Solução:** Defina timeouts do cliente para \~150 segundos. Para qualquer coisa que provavelmente leve muito tempo de qualquer forma, use [Entrega assíncrona](https://developers.oxylabs.io/products/pt-br/api-da-web/scrape/modos-de-entrega.md#single-job-delivery-async) em vez de manter a conexão aberta.

## Erros específicos de mídia (`/scrape/media`)

`/media` e seus jobs de subendpoints podem terminar com HTTP `200` e `state: "done"`, mas retornar nenhum dado ou arquivo com erro específico de mídia em `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 aplicam a `/media/youtube/metadata`, `/media/youtube/subtitles` e `/media/youtube/download` apenas endpoints.
{% endhint %}

<table><thead><tr><th width="219">Erro</th><th width="271">Descrição</th><th>Solução</th></tr></thead><tbody><tr><td><code>11201</code><br><code>VIDEO_DELETED</code></td><td>O vídeo do YouTube foi excluído.</td><td>Abra a URL em um navegador para confirmar que o vídeo ainda está lá. Tentar novamente o mesmo vídeo não vai ajudar.</td></tr><tr><td><code>11202</code><br><code>VIDEO_UNAVAILABLE</code></td><td>O YouTube informa que o vídeo está indisponível.</td><td>Abra o vídeo em um navegador para verificar se ele reproduz. Se reproduzir, entre em contato com o suporte com o <code>request_id</code>.</td></tr><tr><td><code>11203</code><br><code>VIDEO_PRIVATE</code></td><td>O uploader definiu o vídeo como privado, então apenas ele e os espectadores convidados podem vê-lo.</td><td>Use um vídeo público.</td></tr><tr><td><code>11204</code><br><code>VIDEO_GEO_RESTRICTED</code></td><td>O vídeo não está disponível na região de onde o job foi executado.</td><td>Se você precisar deste vídeo, entre em contato com o suporte com o <code>request_id</code>.</td></tr><tr><td><code>11205</code><br><code>VIDEO_LIVE</code></td><td>O vídeo é uma transmissão ao vivo em andamento.</td><td>Tente novamente depois que a transmissão terminar.</td></tr><tr><td><code>11206</code><br><code>VIDEO_AGE_RESTRICTED</code></td><td>O vídeo tem restrição de idade.</td><td>Vídeos com restrição de idade não podem ser recuperados. Use um vídeo diferente.</td></tr><tr><td><code>11207</code><br><code>VIDEO_MEMBER_ONLY</code></td><td>O vídeo está disponível apenas para membros pagantes do canal.</td><td>Vídeos exclusivos para membros não podem ser recuperados. Use um vídeo diferente.</td></tr><tr><td><code>11208</code><br><code>VIDEO_PREMIUM_ONLY</code></td><td>O vídeo exige uma assinatura do YouTube Premium.</td><td>Vídeos exclusivos do Premium não podem ser recuperados. Use um vídeo diferente.</td></tr><tr><td><code>11209</code><br><code>VIDEO_LIVE_OR_TOO_LONG</code></td><td>O vídeo é uma transmissão ao vivo em andamento ou é longo demais para ser baixado. <code>/media/youtube/download</code> apenas.</td><td>Se o vídeo estiver ao vivo, tente novamente depois que a transmissão terminar. Vídeos de até 12 horas podem ser baixados.</td></tr><tr><td><code>11210</code><br><code>VIDEO_TOO_LONG</code></td><td>O vídeo é longo demais para ser baixado. <code>/media/youtube/download</code> apenas.</td><td>Vídeos de até 12 horas podem ser baixados. Use um vídeo mais curto.</td></tr><tr><td><code>11211</code><br><code>VIDEO_SIGN_IN_REQUIRED</code></td><td>O YouTube exige login para ver o vídeo. <code>/media/youtube/download</code> apenas.</td><td>Vídeos que exigem login não podem ser baixados. Use um vídeo diferente.</td></tr><tr><td><code>11301</code><br><code>MEDIA_UNAVAILABLE</code></td><td>O vídeo foi excluído, ou a postagem à qual ele pertencia não existe mais.</td><td>Abra a URL em um navegador para confirmar que o vídeo ainda está lá. Tentar novamente a mesma URL não vai ajudar.</td></tr><tr><td><code>11302</code><br><code>MEDIA_PRIVATE</code></td><td>O vídeo, ou a conta que o publicou, é privada. Apenas vídeos públicos podem ser baixados.</td><td>Use uma URL para um vídeo público.</td></tr><tr><td><code>11303</code><br><code>MEDIA_GEO_RESTRICTE</code>D</td><td>O vídeo não está disponível na região de execução do job. O <code>/media</code> endpoint não tem <code>location</code> parâmetro, então a região não pode ser alterada na requisição.</td><td>Se você precisar deste vídeo, entre em contato com o suporte com o <code>request_id</code>.</td></tr><tr><td><code>11304</code><br><code>MEDIA_UNSUPPORTED</code></td><td>Nenhum vídeo encontrado na URL: uma postagem de foto ou slideshow, uma transmissão ao vivo, uma postagem sem vídeo ou um vídeo longo demais ou grande demais para ser baixado.</td><td>Verifique se a URL corresponde a um dos formatos aceitos e aponta para um único vídeo gravado.</td></tr><tr><td>O vídeo não chega ao seu bucket</td><td><code>storage.url</code> não é validado. Um bucket ou caminho com erro de digitação é aceito, e o job é executado e cobrado, mas o upload falha.</td><td>Verifique <code>storage.type</code> e <code>storage.url</code> antes de enviar. Para <code>s3_compatible</code> e <code>tos</code>, <code>storage.url</code> deve ser uma URL completa com credenciais, por exemplo <code>https://key:secret@host/bucket/path</code>.</td></tr></tbody></table>

## Relatar um problema

Se um problema na API persistir, capture o identificador único da requisição do payload de resposta antes de abrir um ticket com [Suporte Técnico da Oxylabs](mailto:support@oxylabs.io).

* **Campo da resposta:** `metadata.request_id` (por exemplo, `"1788875675880097469"`)
* **Campo de erro do gateway:** `trace_id` (por exemplo, `"d940ba3c-2109-4391-a292-9f2c0613a656"`)

Incluindo o `request_id` or `trace_id` permite que nosso suporte localize imediatamente jobs, dados de roteamento do nó proxy e códigos de resposta 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/pt-br/api-da-web/solucao-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.
