MostlyQR

Errores

La API REST utiliza códigos de estado HTTP estándar y devuelve un cuerpo de error JSON:

json
{ "error": "unauthorized", "message": "Missing or invalid API key" }

# Códigos de estado

Estado error Cuándo
400 invalid-argument Cuerpo malformado o campo requerido faltante.
401 unauthorized Clave de API faltante, inválida o revocada.
403 permission-denied Más allá de los derechos de tu plan (una función que tu plan no incluye).
404 not-found No hay enlace/campaña/trabajo con ese id, o no es propiedad de tu cuenta.
405 method_not_allowed Ese método HTTP no es compatible en la ruta.
409 failed-precondition El recurso no está en un estado que permita la operación — p. ej. editar un enlace congelado, o acuñar códigos serializados más allá de tu asignación Enterprise (el límite está en el mensaje).
429 rate_limited / resource-exhausted Límite de velocidad por clave alcanzado (rate_limited — incluye una marca de tiempo retry_at y encabezados de respuesta X-RateLimit-*) o cuota de plan agotada (resource-exhausted). Retrocede e intenta de nuevo.
5xx internal Algo salió mal de nuestra parte; es seguro reintentar lecturas idempotentes.

Los errores a nivel de transporte (autenticación, enrutamiento, limitación de velocidad) utilizan códigos snake_case; los errores a nivel de recurso utilizan kebab-case (la convención de Firebase callable). Siempre ramifica en el estado HTTP, no en la cadena error.

# Propiedad

Toda lectura y escritura está limitada a la cuenta en la que se resuelve la clave de API. Solicitar un enlace o campaña de otra cuenta devuelve 404 (no 403) — no revelamos que existe.

# Trabajos asincronos

Los trabajos de lote y acuñación serializada aceptan la solicitud (200, queued), luego muestran fallos en el estado del trabajo (status: "failed" con un motivo), no en la respuesta HTTP original. Siempre sondea el trabajo.

# Verificación

Los puntos finales públicos de verificación nunca generan errores en un número de serie desconocido — devuelven status: "unknown" (un código falso/no emitido es una respuesta significativa, no un 404).

# Siguiente