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

# Solução de problemas

Códigos de status da API Web, formatos de resposta de erro, política de repetição e soluções comuns de solução de problemas.

## Códigos de status

| Status + código                                    | Descrição                                                                                                   | Repetir?                                                                                 |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `200 OK`                                           | Resultado Realtime no corpo da resposta                                                                     | –                                                                                        |
| `202 ACEITO`                                       | Job assíncrono aceito                                                                                       | –                                                                                        |
| `400 CORPO_DA_REQUISIÇÃO_MALFORMADO`               | O corpo da requisição não é um JSON válido                                                                  | Não, corrija a formatação do payload.                                                    |
| `400 ERRO_DE_VALIDAÇÃO`                            | Um ou mais campos falharam na validação.                                                                    | Não, corrija todas as entradas em `errors[]` antes de reenviar.                          |
| `401 NÃO_AUTORIZADO`                               | Erro de autenticação (chave ausente, inválida, malformada ou revogada). Sem corpo de resposta neste status. | Não, corrija as credenciais.                                                             |
| `404 NÃO_ENCONTRADO`                               | Um caminho em `/search` não existe ou o `request_id` não existe ou expirou.                                 | Não                                                                                      |
| `405 MÉTODO_NÃO_PERMITIDO`                         | Método HTTP incorreto usado (os endpoints exigem `POST`).                                                   | Não                                                                                      |
| `408 TEMPO_LIMITE_DA_REQUISIÇÃO`                   | `/scrape` apenas. O scraper não respondeu dentro da janela de espera do servidor                            | Sim, com backoff.                                                                        |
| `429 REQUISIÇÕES_DEMAIS`                           | Limite de taxa ou cota excedido. 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 FALHA_DA_REQUISIÇÃO_APÓS_DIVERSAS_TENTATIVAS` | Todos os mecanismos upstream falharam. Não houve cobrança.                                                  | Sim, com backoff.                                                                        |
| `500 ERRO_INTERNO_DO_SERVIDOR`                     | Falha inesperada do sistema                                                                                 | Sim, com backoff.                                                                        |
| `503 SERVIÇO_INDISPONÍVEL`                         | 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 da 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": "A entrada deve ser menor ou igual a 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>estado</code></td><td>Presente em <code>500</code> respostas (<code>"faulted"</code>). Chamadas bem-sucedidas retornam <code>"done"</code>.</td><td>cadeia de caracteres</td></tr><tr><td><code>título</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>detalhe</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>instância</code></td><td>Identificador de rastreamento da requisição. Inclua em solicitações de suporte.</td><td>cadeia de caracteres</td></tr><tr><td><code>metadata.request_id</code></td><td>Identificador da requisição com 19 dígitos usado para rastreamento e suporte.</td><td>cadeia de caracteres</td></tr><tr><td><code>metadata.timestamp</code></td><td>Carimbo de data/hora Unix em segundos.</td><td>número</td></tr><tr><td><code>parâmetros</code></td><td>Todos os parâmetros usados na requisição com os 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

Repetir `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 resolverá isso.

## Erros comuns e soluções

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

Tanto violações de limite de taxa (excedendo a concorrência de requisições por segundo) quanto o esgotamento da cota da conta retornam um HTTP `429 Muitas requisições` código.

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

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

Renderização em Headless Browser (`run_js: true`) ou sites-alvo complexos exigem muito mais tempo de processamento do que buscas HTML padrão, frequentemente 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](/products/pt-br/api-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 subendpoint podem terminar com HTTP `200` e `estado: "done"`, mas não retornam dados 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": "O vídeo tem restrição de idade."
    }
}
```

{% endcode %}

{% hint style="info" %}
`11201`-`11211` se aplicam a `/media/youtube/metadata`, `/media/youtube/subtitles` e `/media/youtube/download` apenas os 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 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 job's <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 job's <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 após 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 outro vídeo.</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 outro vídeo.</td></tr><tr><td><code>11208</code><br><code>VIDEO_PREMIUM_ONLY</code></td><td>O vídeo requer uma assinatura do YouTube Premium.</td><td>Vídeos exclusivos do Premium não podem ser recuperados. Use outro vídeo.</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 baixar. <code>/media/youtube/download</code> apenas.</td><td>Se o vídeo estiver ao vivo, tente novamente após 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 baixar. <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 outro vídeo.</td></tr><tr><td><code>11301</code><br><code>MEDIA_UNAVAILABLE</code></td><td>O vídeo foi excluído, ou a publicação à 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 ajudará.</td></tr><tr><td><code>11302</code><br><code>MEDIA_PRIVATE</code></td><td>O vídeo, ou a conta que o publicou, é privado. 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 do job. O <code>/media</code> endpoint não tem nenhum <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 job's <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 publicação de foto ou slideshow, uma transmissão ao vivo, uma publicação sem vídeo, ou um vídeo muito longo ou grande demais para baixar.</td><td>Verifique se a URL corresponde a um dos formatos de URL 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>

## Reportando um problema

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

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

Incluir o `request_id` ou `trace_id` permite que nosso suporte localize imediatamente jobs, dados de roteamento dos nós 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-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.