> 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/pt-br/erros-e-codigos-de-status.md).

# Erros e códigos de status

Especificação técnica para códigos de status HTTP, documentos de problema RFC 9457, classificação de erros e lógica de retentativa em produção para a Oxylabs Web API.

### Matriz de status code e retry

A lógica de retry deve ser controlada estritamente pelos códigos de status HTTP da resposta. Repetir erros de cliente não repetíveis (`400`, `401`, `403`, `404`) causa falhas idênticas e carga desnecessária na API.

<table><thead><tr><th width="207">Status + Código</th><th width="183">Título RFC 9457</th><th>Descrição</th><th width="117">Retryável?</th></tr></thead><tbody><tr><td><code>200 OK</code></td><td>—</td><td>Chamada Realtime bem-sucedida. Execução concluída; processe o corpo da resposta.</td><td>Não</td></tr><tr><td><code>202 Accepted</code></td><td>—</td><td>Job assíncrono aceito. Job enfileirado; recuperar via <code>metadata.request_id</code>.</td><td>Não</td></tr><tr><td><code>400 Bad Request</code></td><td><code>INVALID_BODY_PROPERTY</code>, <code>MALFORMED_JSON</code></td><td>Payload de validação ou malformado. Corrija os parâmetros em <code>errors[]</code> antes de reenviar.</td><td>Não</td></tr><tr><td><code>401 Unauthorized</code></td><td>— <em>(Corpo vazio)</em></td><td>Chave de API inválida, ausente ou revogada. Verifique o formato do token Bearer e a chave da instância no dashboard.</td><td>Não</td></tr><tr><td><code>403 Forbidden</code></td><td>—</td><td>Restrição de permissão. A conta não tem acesso à rota de destino ou à fonte.</td><td>Não</td></tr><tr><td><code>404 Not Found</code></td><td><code>NOT_FOUND</code></td><td>Rota ou ID do job inválido/expirado. Verifique o caminho do endpoint ou o identificador da solicitação assíncrona.</td><td>Não</td></tr><tr><td><code>405 Method Not Allowed</code></td><td><code>METHOD_NOT_ALLOWED</code></td><td>Método diferente de <code>POST</code> usado. Altere o método da solicitação HTTP para <code>POST</code>.</td><td>Não</td></tr><tr><td><code>408 Request Timeout</code></td><td>—</td><td>Timeout de scraping Realtime. Tente novamente usando backoff exponencial.</td><td>Sim</td></tr><tr><td><code>413 Payload Too Large</code></td><td>—</td><td>O tamanho do payload ou do lote foi excedido. Reduza o tamanho do payload ou a contagem de destinos por lote.</td><td>Não</td></tr><tr><td><code>429 Too Many Requests</code></td><td>—</td><td>Limite de concorrência ou cota esgotado. Reduza a concorrência e aplique backoff com jitter. Avise o operador se persistir.</td><td><p>Limite de taxa: Sim</p><p>Cota: Não</p></td></tr><tr><td><code>500 Internal Error</code></td><td><code>REQUEST_FAILED_AFTER_TOO_MANY_RETRIES</code>, <code>INTERNAL_ERROR</code></td><td>Falha upstream ou scrape com estado faulted. Scrapes faulted não são cobrados. Tente novamente com backoff.</td><td>Sim</td></tr><tr><td><code>503 Service Unavailable</code></td><td><code>SERVICE_UNAVAILABLE</code></td><td>Serviço temporariamente indisponível. Tente novamente com backoff.</td><td>Sim</td></tr></tbody></table>

### Documentos de problema RFC 9457

Quando ocorre um erro HTTP, a Web API retorna um [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) documento de problema servido como `application/problem+json`.

{% hint style="info" %}
`401 Unauthorized` Exceção: HTTP `401` As respostas de status vêm com corpo vazio. O próprio código de status HTTP representa o estado completo de falha de autenticação.
{% endhint %}

#### 1. Propriedade de corpo inválida (`400 Bad Request`)

Uma `storage.url` retorna `VALIDATION_ERROR` com `errors[].pointer` definido como `#/storage/url`. A solicitação não é criada.

```json
{
  "status": 400,
  "title": "INVALID_BODY_PROPERTY",
  "detail": "Uma propriedade do corpo tem um valor inválido.",
  "instance": "6ad5c6df-4ef52bbe9bd1519f8dbfc4ae",
  "errors": [
    {
      "detail": "Deve ser um dos seguintes: gcs, s3, s3_gzip, s3_compatible, tos.",
      "pointer": "#/storage/type"
    }
  ]
}
```

#### 2. Erro de scrape faulted (`500 Internal Error`)

Se um scrape falhar após todas as tentativas, `POST /v1/scrape` retorna um HTTP `500` status com `state: "faulted"`. Scrapes faulted não consomem a cota da conta.

```json
{
  "status": 500,
  "state": "faulted",
  "title": "REQUEST_FAILED_AFTER_TOO_MANY_RETRIES",
  "detail": "A solicitação falhou após o número máximo de tentativas. Você pode tentar novamente sem custo adicional, pois não cobramos por scrapes faulted.",
  "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"
  }
}
```

### Detalhamento do schema da resposta

<table><thead><tr><th width="192">Caminho do campo</th><th width="99.5">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>status</code></td><td>inteiro</td><td>Código de status HTTP.</td></tr><tr><td><code>state</code></td><td>string</td><td>Presente em respostas de scrape faulted <code>500</code> de scrape (<code>"faulted"</code>). Chamadas bem-sucedidas retornam <code>"done"</code>.</td></tr><tr><td><code>title</code></td><td>string</td><td>Código de erro legível por máquina. Direcione a lógica de erro da aplicação com base nesse valor.</td></tr><tr><td><code>detail</code></td><td>string</td><td>Mensagem de erro legível por humanos. Não analise o texto para ramificações do programa.</td></tr><tr><td><code>instance</code></td><td>string</td><td>Identificador de rastreamento único para depuração interna e escalonamento ao suporte.</td></tr><tr><td><code>metadata.request_id</code></td><td>string</td><td>Identificador de rastreamento de 19 dígitos para cobrança e tickets de suporte.</td></tr><tr><td><code>metadata.timestamp</code></td><td>inteiro</td><td>Timestamp Unix em segundos.</td></tr><tr><td><code>errors[]</code></td><td>array</td><td>Presente em erros de validação da solicitação. Contém objetos de falha por campo.</td></tr><tr><td><code>errors[].pointer</code></td><td>string</td><td>JSON Pointer que identifica o campo inválido da solicitação (por exemplo, <code>#/storage/type</code>).</td></tr><tr><td><code>errors[].detail</code></td><td>string</td><td>Motivo detalhado da falha para o ponteiro de campo especificado.</td></tr></tbody></table>

### Referência do código de erro (`title`)

O roteamento programático de erros deve avaliar o `title` atributo:

<table><thead><tr><th>"title" Código</th><th width="122">Status HTTP</th><th>Descrição</th></tr></thead><tbody><tr><td><code>MALFORMED_JSON</code></td><td><code>400</code></td><td>O corpo da solicitação não é JSON válido.</td></tr><tr><td><code>INVALID_BODY_PROPERTY</code></td><td><code>400</code></td><td>Uma propriedade do corpo da solicitação tem um valor inválido.</td></tr><tr><td><code>NOT_FOUND</code></td><td><code>404</code></td><td>Caminho de rota inválido ou sub-recurso do endpoint não atribuído.</td></tr><tr><td><code>METHOD_NOT_ALLOWED</code></td><td><code>405</code></td><td>Método HTTP incorreto usado (os endpoints da Web API exigem <code>POST</code>).</td></tr><tr><td><code>REQUEST_FAILED_AFTER_TOO_MANY_RETRIES</code></td><td><code>500</code></td><td>O scrape falhou após o número máximo de tentativas. Sem cobrança.</td></tr><tr><td><code>INTERNAL_ERROR</code></td><td><code>500</code></td><td>Erro interno de processamento.</td></tr><tr><td><code>SERVICE_UNAVAILABLE</code></td><td><code>503</code></td><td>Interrupção temporária do serviço de backend.</td></tr></tbody></table>

### Erros específicos de mídia

Retornado por `POST /v1/async/scrape/media` e seus sub-endpoints quando o vídeo não pode ser baixado.

<table><thead><tr><th width="74.03125">Código</th><th width="216.372304199773">Status</th><th>Descrição</th></tr></thead><tbody><tr><td><code>11201</code></td><td><code>VIDEO_DELETED</code></td><td>O vídeo foi excluído.</td></tr><tr><td><code>11202</code></td><td><code>VIDEO_UNAVAILABLE</code></td><td>O vídeo não está disponível.</td></tr><tr><td><code>11203</code></td><td><code>VIDEO_PRIVATE</code></td><td>O vídeo foi definido como privado pelo uploader e somente ele e pessoas explicitamente convidadas podem vê-lo.</td></tr><tr><td><code>11204</code></td><td><code>VIDEO_GEO_RESTRICTED</code></td><td>O vídeo tem restrição geográfica.</td></tr><tr><td><code>11205</code></td><td><code>VIDEO_LIVE</code></td><td>O vídeo está ao vivo agora.</td></tr><tr><td><code>11206</code></td><td><code>VIDEO_AGE_RESTRICTED</code></td><td>O vídeo tem restrição de idade.</td></tr><tr><td><code>11207</code></td><td><code>VIDEO_MEMBER_ONLY</code></td><td>O vídeo é apenas para membros do canal, e os espectadores precisam pagar a taxa mensal de assinatura.</td></tr><tr><td><code>11208</code></td><td><code>VIDEO_PREMIUM_ONLY</code></td><td>O vídeo requer a assinatura do YouTube Premium.</td></tr><tr><td><code>11209</code></td><td><code>VIDEO_LIVE_OR_TOO_LONG</code></td><td>O vídeo está ao vivo ou é longo demais para ser baixado.</td></tr><tr><td><code>11210</code></td><td><code>VIDEO_TOO_LONG</code></td><td>O vídeo é longo demais para ser baixado.</td></tr><tr><td><code>11211</code></td><td><code>VIDEO_SIGN_IN_REQUIRED</code></td><td>É necessário fazer login.</td></tr><tr><td><code>11301</code></td><td><code>MEDIA_UNAVAILABLE</code></td><td>O vídeo foi excluído ou não existe mais</td></tr><tr><td><code>11302</code></td><td><code>MEDIA_PRIVATE</code></td><td>O vídeo ou a conta é privada</td></tr><tr><td><code>11303</code></td><td><code>MEDIA_GEO_RESTRICTED</code></td><td>O vídeo não está disponível na região do job</td></tr><tr><td><code>11304</code></td><td><code>MEDIA_UNSUPPORTED</code></td><td>Não é um vídeo baixável: uma foto, apresentação de slides, livestream ou postagem sem formatos de vídeo, ou um vídeo longo demais ou grande demais para ser baixado</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/pt-br/erros-e-codigos-de-status.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.