PDF Blocks
PreçosSuporte
Começar grátis
Abrir a página

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, 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.

{
  "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.

{
  "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.

{
  "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 e envie a requisição por HTTPS. Consulte Autenticação.

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.

{
  "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 válida.

406: Accept inaceitável

Uma ação de vários documentos recebeu um cabeçalho Accept que ela não consegue atender.

{
  "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.

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.

402: pagamento necessário. Uma condição de faturamento ou de cota no seu plano.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

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.

Leia sempre o objeto errors quando ele estiver presente: ele nomeia exatamente o que corrigir.