Referencia de errores

Todos los errores de la API de qr3.app siguen RFC 7807 Problem Details con Content-Type: application/problem+json.

{
  "type": "https://docs.qr3.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "QR code qr_xxx not found"
}

`errors/validation`

HTTP 422 Unprocessable Entity

Los datos de entrada no superaron la validación del esquema. La respuesta contiene un array errors con detalles específicos de cada campo.

{
  "type": "https://docs.qr3.app/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request body validation failed",
  "errors": [
    { "field": "url", "message": "Invalid URL format" }
  ]
}

Causas: Campos obligatorios ausentes, tipos de datos incorrectos, valores fuera del rango permitido, formato de URL no válido.

`errors/bad-request`

HTTP 400 Bad Request

El cuerpo no es un JSON válido aunque Content-Type: application/json esté establecido (por ejemplo, una coma final, un cuerpo truncado o vacío).

`errors/authentication`

HTTP 401 Unauthorized

La clave de API falta, tiene un formato incorrecto, ha expirado o ha sido revocada.

Solución: Comprueba si la cabecera Authorization: Bearer qr3_sk_... está presente y si la clave está activa.

`errors/unauthorized`

HTTP 401 Unauthorized

Se llamó a un webhook entrante (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) sin una firma o secreto válidos. Si falta una clave de API o esta no es válida, se responde con errors/authentication en su lugar.

`errors/authorization`

HTTP 403 Forbidden

La clave de API es válida, pero no tiene el alcance (scope) o los permisos necesarios.

`errors/forbidden`

HTTP 403 Forbidden

El recurso existe, pero pertenece a otro Workspace u otra organización.

`errors/document-immutable`

HTTP 403 Forbidden

Un documento de DPP subido con is_immutable no se puede eliminar.

`errors/not-found`

HTTP 404 Not Found

El recurso solicitado no existe o ha sido eliminado.

`errors/conflict`

HTTP 409 Conflict

Ya existe un recurso con el mismo identificador único (por ejemplo, slug duplicado o colisión de Idempotency-Key).

`errors/subscription-exists`

HTTP 409 Conflict

Se llamó a POST /v1/billing/checkout aunque la organización ya tiene una suscripción. Cambia el plan en el portal de facturación en su lugar.

`errors/rate-limited`

HTTP 429 Too Many Requests

Se ha excedido el límite de velocidad (rate limit) por minuto de la clave de API. La respuesta contiene las cabeceras Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

Se ha excedido un límite de velocidad específico del recurso (por ejemplo, 200 códigos QR al día por Workspace).

`errors/plan-limit`

HTTP 422 Unprocessable Entity

Tu plan actual no permite esta acción (por ejemplo, cuota de DPP o de códigos dinámicos agotada, lote demasiado grande, demasiados espacios de trabajo o miembros del equipo). Se requiere una actualización.

`errors/invalid-file-type`

HTTP 400 Bad Request

El archivo subido tiene un tipo que el endpoint no acepta, o su contenido no coincide con el Content-Type declarado.

`errors/file-too-large`

HTTP 413 Payload Too Large

El archivo subido supera el límite de tamaño del plan o del endpoint.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

La subida superaría el almacenamiento total del espacio de trabajo o del DPP.

`errors/not-configured`

HTTP 503 Service Unavailable

Falta un servicio o configuración requerida (por ejemplo, Stripe no configurado, clave de API de Web Risk no establecida).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

La URL fue rechazada porque Google Web Risk la clasificó como no segura (malware, phishing, ingeniería social).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Reservado para URLs que posteriormente se clasificaron como no seguras durante el re-escaneo periódico.

`errors/already-submitted`

HTTP 409 Conflict

Envío duplicado: por ejemplo, ya se ha enviado una puntuación NPS para este Workspace este mes.

`errors/unprocessable-entity`

HTTP 422 Unprocessable Entity

Una acción de administrador no está permitida (por ejemplo, suplantar a otro superadmin). Solo los endpoints de superadmin devuelven este tipo.

`errors/request-error`

HTTP 4xx Client Error

Tipo de reserva para errores del cliente sin un tipo más específico; el estado se encuentra en la respuesta. La API actualmente no tiene ninguna ruta conocida que lo devuelva.

`errors/internal`

HTTP 500 Internal Server Error

Un error inesperado en el servidor. Por favor, vuelve a intentar la solicitud. Si los problemas persisten: [email protected].