PDF Blocks
PreciosSoporte
Empezar gratis
Ir a la página

Errores

El formato de errores problem+json, qué significa cada código de estado y cómo tratar en código una solicitud fallida.

Cuando una solicitud falla, PDF Blocks devuelve un código de estado HTTP estándar y un cuerpo legible por máquina que describe qué ha ido mal. Los errores siguen el formato problem details de RFC 7807, así que puede analizar todos los fallos igual, sea cual sea la acción que los produjo.

El modelo problem+json

Las respuestas de error llevan Content-Type: application/problem+json y esta forma:

Atributo Tipo Descripción
type string Una URL con documentación sobre el problema.
title string Un resumen del problema legible por personas.
status integer El código de estado HTTP, repetido en el cuerpo.
errors object Nombres de campo asociados a matrices de mensajes de error.

La URL de type siempre termina en el código de estado, por ejemplo https://www.pdfblocks.com/docs/api/v1/error/400, de modo que puede ramificar según ella o según status. El objeto errors aparece cuando el fallo está ligado a campos concretos de la solicitud (validación); en fallos a nivel de solicitud, como una clave de API incorrecta, puede omitirse.

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

Estado Significado Qué hacer
400 Error de validación Corrija los campos indicados y vuelva a enviar.
401 No autorizado Envíe un X-API-Key válido.
404 No encontrado Compruebe la ruta de la acción y el host.
406 Accept no aceptable Solicite un formato admitido.
402 Pago requerido (reservado) Resuelva la facturación o la cuota.
403 Prohibido (reservado) La clave no tiene permiso para esta llamada.
413 Carga demasiado grande (reservado) Envíe un archivo más pequeño.
429 Demasiadas solicitudes (reservado) Espere y vuelva a intentarlo.
5xx Error del servidor (poco frecuente) Reintente con espera exponencial.

400: error de validación

Un parámetro no es válido, o file no es un PDF legible. El objeto errors indica 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."]
  }
}

Lea errors campo por campo, corrija la entrada y vuelva a enviarla. Un 400 no tendrá éxito al reintentarlo sin cambios.

401: no autorizado

La cabecera X-API-Key falta, está mal formada o no es una clave válida.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/401",
  "title": "The request is missing a valid API key.",
  "status": 401
}

Establezca en la cabecera X-API-Key una clave válida de su dashboard y envíe la solicitud por HTTPS. Consulte Autenticación.

404: no encontrado

La ruta no resuelve a ninguna acción, normalmente por un error tipográfico en el nombre de la acción o por falta del segmento de versión.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/404",
  "title": "The requested resource was not found.",
  "status": 404
}

Verifique la ruta (por ejemplo /v1/add_text_watermark) y que está llamando a una URL base válida.

406: Accept no aceptable

Una acción de varios documentos ha recibido una cabecera Accept que no puede satisfacer.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/406",
  "title": "The requested Accept header cannot be satisfied.",
  "status": 406
}

Solicite uno de los formatos admitidos, application/zip, application/json o multipart/mixed, u omita Accept para obtener el ZIP predeterminado. Consulte Formatos de respuesta.

Códigos de estado reservados

Con vistas al futuro. Las respuestas 402, 403, 413 y 429 forman parte del contrato de la API pero todavía no se aplican. Trátelas desde ya para que su cliente esté listo cuando entren en vigor. Los detalles de uso y de rate limits están en Rate limits y uso.

402: pago requerido. Una condición de facturación o de cuota de su plan.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/402",
  "title": "Payment is required to complete this request.",
  "status": 402
}

403: prohibido. La clave es válida pero no tiene permiso 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: carga demasiado grande. El cuerpo de la solicitud supera el tamaño admitido.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/413",
  "title": "The request payload is too large.",
  "status": 413
}

429: demasiadas solicitudes. Ha superado el rate limit de su plan.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/429",
  "title": "Too many requests. Please retry later.",
  "status": 429
}

5xx: errores del servidor

Un estado 5xx indica un problema de nuestro lado y es poco frecuente. Es transitorio: reintente la misma solicitud con espera exponencial.

Cómo tratar los errores en el código

Analice el cuerpo una vez y ramifique según status (o según el estado final de type):

  • 400: lea el objeto errors, asocie cada mensaje a su campo y corrija la entrada. No reintente a ciegas; la misma solicitud volverá a fallar.
  • 401, 403, 404, 406: la solicitud en sí es incorrecta. Corrija la cabecera, la ruta o Accept y vuelva a enviarla; reintentarla sin cambios no servirá.
  • 402, 413: una condición de cuenta o de tamaño. Resuelva la facturación o envíe un archivo más pequeño; tal cual no tendrán éxito al reintentar.
  • 429 y 5xx: transitorios. Reintente con espera exponencial, respete la cabecera Retry-After cuando esté presente y limite el número de intentos. Consulte Rate limits y uso.

Lea siempre el objeto errors cuando esté presente: indica exactamente qué hay que corregir.