# Erros O formato de erro problem+json, o que cada código de status significa e como tratar no código uma requisição que falhou. Quando uma requisição falha, o PDF Blocks retorna um código de status HTTP padrão e um corpo legível por máquina descrevendo o que deu errado. Os erros seguem os problem details da [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807), então você analisa toda falha da mesma forma, seja qual for a ação que a produziu. ## O modelo problem+json As respostas de erro têm `Content-Type: application/problem+json` e este formato: | Atributo | Tipo | Descrição | | --------- | ------- | ------------------------------------------------------------ | | `type` | string | Uma URL para a documentação sobre o problema. | | `title` | string | Um resumo do problema legível por humanos. | | `status` | integer | O código de status HTTP, repetido no corpo. | | `errors` | object | Nomes de campos associados a matrizes de mensagens de erro. | A URL de `type` sempre termina no código de status (por exemplo `https://www.pdfblocks.com/docs/api/v1/error/400`), então você pode ramificar por ela ou por `status`. O objeto `errors` está presente quando a falha está ligada a campos específicos da requisição (validação); em falhas no nível da requisição, como uma chave de API incorreta, ele pode ser omitido. ```json { "type": "https://www.pdfblocks.com/docs/api/v1/error/400", "title": "One or more validation errors occurred.", "status": 400, "errors": { "file": [ "Could not parse the PDF document. The file may be invalid or corrupt." ] } } ``` ## Códigos de status | Status | Significado | O que fazer | | ------ | ------------------------------------ | ---------------------------------------- | | `400` | Erro de validação | Corrija os campos indicados e reenvie. | | `401` | Não autorizado | Envie um `X-API-Key` válido. | | `404` | Não encontrado | Verifique a rota da ação e o host. | | `406` | `Accept` inaceitável | Peça um formato compatível. | | `402` | Pagamento necessário *(reservado)* | Resolva o faturamento ou a cota. | | `403` | Proibido *(reservado)* | A chave não pode fazer esta chamada. | | `413` | Corpo grande demais *(reservado)* | Envie um arquivo menor. | | `429` | Requisições em excesso *(reservado)* | Reduza o ritmo e tente de novo. | | `5xx` | Erro do servidor (raro) | Tente de novo com backoff. | ### 400: erro de validação Um parâmetro é inválido ou `file` não é um PDF legível. O objeto `errors` nomeia cada campo problemático. ```json { "type": "https://www.pdfblocks.com/docs/api/v1/error/400", "title": "One or more validation errors occurred.", "status": 400, "errors": { "line_1": ["The field line_1 must be a string with a maximum length of 32."] } } ``` Leia `errors` campo a campo, corrija a entrada e reenvie. Um `400` não vai passar em uma nova tentativa sem alterações. ### 401: não autorizado O cabeçalho `X-API-Key` está ausente, malformado ou não contém uma chave válida. ```json { "type": "https://www.pdfblocks.com/docs/api/v1/error/401", "title": "The request is missing a valid API key.", "status": 401 } ``` Defina o cabeçalho `X-API-Key` com uma chave válida do seu [dashboard](https://dashboard.pdfblocks.com) e envie a requisição por HTTPS. Consulte [Autenticação](/docs/api/authentication). ### 404: não encontrado O caminho não corresponde a nenhuma ação, normalmente por um erro de digitação no nome da ação ou por um segmento de versão ausente. ```json { "type": "https://www.pdfblocks.com/docs/api/v1/error/404", "title": "The requested resource was not found.", "status": 404 } ``` Verifique a rota (por exemplo `/v1/add_text_watermark`) e se você está chamando uma [URL base](/docs/api/regions-and-data-residency) válida. ### 406: `Accept` inaceitável Uma ação de vários documentos recebeu um cabeçalho `Accept` que ela não consegue atender. ```json { "type": "https://www.pdfblocks.com/docs/api/v1/error/406", "title": "The requested Accept header cannot be satisfied.", "status": 406 } ``` Peça um dos formatos compatíveis (`application/zip`, `application/json` ou `multipart/mixed`) ou omita `Accept` para receber o ZIP padrão. Consulte [Formatos de resposta](/docs/api/response-formats). ### Códigos de status reservados **Olhando para a frente.** As respostas `402`, `403`, `413` e `429` fazem parte do contrato da API, mas **ainda não são aplicadas**. Trate-as desde já para que seu cliente esteja pronto quando elas entrarem em vigor. Os detalhes de uso e de rate limiting estão em [Rate limits e uso](/docs/api/rate-limits-and-usage). **`402`: pagamento necessário.** Uma condição de faturamento ou de cota no seu plano. ```json { "type": "https://www.pdfblocks.com/docs/api/v1/error/402", "title": "Payment is required to complete this request.", "status": 402 } ``` **`403`: proibido.** A chave é válida, mas não tem permissão para usar este recurso. ```json { "type": "https://www.pdfblocks.com/docs/api/v1/error/403", "title": "You do not have permission to access this resource.", "status": 403 } ``` **`413`: corpo grande demais.** O corpo da requisição excede o tamanho aceito. ```json { "type": "https://www.pdfblocks.com/docs/api/v1/error/413", "title": "The request payload is too large.", "status": 413 } ``` **`429`: requisições em excesso.** Você excedeu a taxa de requisições permitida pelo seu plano. ```json { "type": "https://www.pdfblocks.com/docs/api/v1/error/429", "title": "Too many requests. Please retry later.", "status": 429 } ``` ### 5xx: erros do servidor Um status `5xx` indica um problema do nosso lado e é raro. Ele é transitório: repita a mesma requisição com [backoff exponencial](/docs/api/rate-limits-and-usage). ## Tratar erros no código Analise o corpo uma única vez e ramifique por `status` (ou pelo status no fim de `type`): - **`400`**: leia o objeto `errors`, associe cada mensagem ao seu campo e corrija a entrada. Não repita a requisição às cegas; ela vai falhar de novo. - **`401`, `403`, `404`, `406`**: a própria requisição está errada. Corrija o cabeçalho, a rota ou o `Accept` e reenvie; repetir sem alterações não adianta. - **`402`, `413`**: uma condição de conta ou de tamanho. Resolva o faturamento ou envie um arquivo menor; do jeito que estão, essas requisições não passam em uma nova tentativa. - **`429` e `5xx`**: transitórios. Repita com backoff exponencial, respeite o cabeçalho `Retry-After` quando ele estiver presente e limite o número de tentativas. Consulte [Rate limits e uso](/docs/api/rate-limits-and-usage). Leia sempre o objeto `errors` quando ele estiver presente: ele nomeia exatamente o que corrigir.