La API de NueForm utiliza códigos de estado HTTP convencionales y devuelve respuestas de error JSON estructuradas. Esta guía cubre el formato de respuesta, todos los códigos de error posibles y patrones para manejar errores en tu código.
Formatos de respuesta
Respuestas exitosas
Las llamadas exitosas a la API devuelven un objeto JSON con un campo data. Los endpoints de lista también incluyen un campo meta con información de paginación.
{
"data": {
"id": "clx1abc2d3e4f5g6h7i8j9k0",
"title": "Customer Feedback",
"status": "published",
"created_at": "2026-01-15T09:30:00.000Z"
}
}
Con metadatos de paginación:
{
"data": [
{
"id": "clx1abc2d3e4f5g6h7i8j9k0",
"title": "Customer Feedback"
},
{
"id": "clx2def3g4h5i6j7k8l9m0n1",
"title": "Employee Survey"
}
],
"meta": {
"page": 1,
"per_page": 20,
"total": 150,
"total_pages": 8
}
}
Respuestas de error
Las respuestas de error devuelven un objeto JSON con un campo error que contiene el code de error, un message legible para humanos y el código de status HTTP.
{
"error": {
"code": "NOT_FOUND",
"message": "The requested form could not be found.",
"status": 404
}
}
Códigos de error
La siguiente tabla lista todos los códigos de error devueltos por la API:
| Código | Estado HTTP | Descripción |
|---|---|---|
BAD_REQUEST | 400 | La solicitud está mal formada, faltan campos requeridos o contiene valores inválidos. |
UNAUTHORIZED | 401 | La autenticación falló. La clave de API falta, está mal formada, revocada o expirada. |
FORBIDDEN | 403 | El usuario autenticado no tiene permiso para realizar esta acción. |
NOT_FOUND | 404 | El recurso solicitado no existe o no es accesible para el usuario autenticado. |
CONFLICT | 409 | La solicitud entra en conflicto con el estado actual del recurso (por ejemplo, una entrada duplicada o un formulario que todavía no se puede publicar). |
RATE_LIMITED | 429 | Demasiadas solicitudes. Consulta Límites de velocidad para más detalles. |
INTERNAL_ERROR | 500 | Ocurrió un error inesperado en el servidor. |
Ejemplos de respuestas de error
400 Bad Request
Se devuelve cuando el cuerpo de la solicitud es inválido o faltan campos requeridos.
{
"error": {
"code": "BAD_REQUEST",
"message": "Field 'title' is required.",
"status": 400
}
}
401 Unauthorized
Se devuelve cuando la autenticación falla por cualquier motivo.
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or expired API key.",
"status": 401
}
}
403 Forbidden
Se devuelve cuando el usuario está autenticado pero carece de permisos. Las causas comunes incluyen acceder a recursos de otro usuario o usar una función no disponible en el plan actual.
{
"error": {
"code": "FORBIDDEN",
"message": "API access is not available on your current plan.",
"status": 403
}
}
404 Not Found
Se devuelve cuando el recurso solicitado no existe.
{
"error": {
"code": "NOT_FOUND",
"message": "The requested form could not be found.",
"status": 404
}
}
409 Conflict
Se devuelve cuando la solicitud crearía un duplicado o entra en conflicto con datos existentes.
{
"error": {
"code": "CONFLICT",
"message": "A form with this slug already exists.",
"status": 409
}
}
409 Conflict — publicación bloqueada
Lo devuelve POST /api/v1/forms/:id/publish (y PUT /api/v1/forms/:id con published: true) cuando el formulario todavía no puede publicarse. No se publica nada. reason indica el motivo y question_ids enumera las preguntas que hay que corregir. Cuando upgrade_required es true, hay que mejorar el plan del propietario del formulario.
{
"error": {
"code": "CONFLICT",
"message": "E-signature contracts need a Pro plan to go live. Upgrade to publish this form, or remove the contract question.",
"status": 409,
"reason": "contract_requires_pro",
"question_ids": ["66a1b2c3d4e5f6a7b8c9d001"],
"upgrade_required": true
}
}
reason | Qué corregir |
|---|---|
contract_requires_pro, data_node_requires_pro, booking_requires_pro, payment_connect_requires_pro, webhook_requires_pro | El plan del propietario del formulario (el del propietario del equipo en los formularios de equipo) no incluye esta función. Mejora el plan o quita la función: elimina la pregunta, vacía webhook_url o cambia la pregunta de pago a la opción estándar. |
booking_* | Una pregunta de reserva todavía no puede aceptar reservas: conecta o vuelve a conectar su calendario, o añade su horario, su zona horaria, sus opciones de duración o el número para las llamadas de confirmación. |
email_node_* | A un paso de email le falta el destinatario, el nombre del remitente, el asunto o el cuerpo, o envía a {respondent.email} en un formulario que no requiere iniciar sesión. |
fuse_* | Una pregunta Fuse no tiene formulario Fuse, su formulario Fuse no existe o no está publicado, o su sesión fijada se archivó. |
composite_* | Un compuesto que usa el formulario no está publicado, se eliminó o está vacío; composite_ids los enumera. |
Si creas un formulario con published: true y su publicación se bloquea, el formulario se crea igualmente como borrador: la respuesta es 201 Created con un objeto publish_error (reason, message, question_ids, upgrade_required), así que reintentar nunca crea un duplicado. Cuando PUT /api/v1/forms/:id devuelve este error, tus cambios se guardaron (saved_as_draft: true) y solo falló la publicación.
429 Rate Limited
Se devuelve cuando se ha excedido el límite de velocidad. Incluye un encabezado Retry-After.
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Please try again later.",
"status": 429
}
}
500 Internal Error
Se devuelve cuando ocurre un error inesperado del servidor. Si persiste, contacta con soporte.
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An internal error occurred.",
"status": 500
}
}
Errores de la API de voz
La API de voz añade estos códigos. Nada que termine en error se cobra, y los campos adicionales van junto a code dentro de error.
| Código | Estado HTTP | Descripción |
|---|---|---|
INSUFFICIENT_CREDITS | 402 | Tu saldo no cubre la solicitud. credits_required, credits_available y top_up_url indican cuánto falta y dónde conseguir más. |
TEXT_TOO_LONG | 413 | Más caracteres hablados de los que acepta una solicitud (max_characters). Divide el texto en varias solicitudes. |
CONTENT_BLOCKED | 422 | El texto no se puede hablar según nuestra política de uso (categories). |
VOICE_UNAVAILABLE | 422 | La voz no existe o no puedes usarla (voice). |
LANGUAGE_NOT_SUPPORTED_BY_VOICE | 422 | La voz no puede hablar ese idioma (voice, language, supported_languages). |
LINE_LANGUAGE_NOT_SUPPORTED_BY_VOICE | 422 | Algunas líneas están en un idioma que su propia voz no puede hablar. mismatches enumera cada una (speaker, voice, voice_name, language, line_count) con hasta cuatro suggestions de voces que sí lo hablan. Si native_voices es false, ninguna voz habla ese idioma: las sugerencias hablan un idioma cercano y puede que no suenen bien. |
INVALID_SCRIPT | 422 | El guion no se puede hablar tal como se envió (reason, por ejemplo speaker_not_cast). |
CONCURRENCY_LIMIT | 429 | Demasiadas generaciones en curso a la vez en tu cuenta. Vuelve a intentarlo después de Retry-After. |
CAPACITY | 503 | No hay capacidad en este momento. Vuelve a intentarlo después de Retry-After. |
WARMING_UP | 503 | El motor de voz se está iniciando. Vuelve a intentarlo después de Retry-After. |
MODERATION_UNAVAILABLE | 503 | No se pudo revisar el texto en este momento. Vuelve a intentarlo después de Retry-After. |
AI_UNAVAILABLE | 503 | auto_convert o auto_cast no se pudo ejecutar en este momento. Vuelve a intentarlo después de Retry-After. |
DELETE_INCOMPLETE | 503 | Una eliminación se detuvo a medias. Vuelve a enviarla para terminarla. |
FORBIDDEN (403) y CONFLICT (409) indican el motivo en reason: por ejemplo key_limit_reached, account_gate o scope_not_allowed, y quote_exceeds_max_credits, idempotency_conflict o request_in_progress.
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "This request needs 30 credits; 12 are available. Nothing was charged.",
"status": 402,
"credits_required": 30,
"credits_available": 12,
"top_up_url": "https://nueform.io/wallet?tab=buy"
}
}
Manejo de errores en código
JavaScript
Construye un cliente de API reutilizable que verifique errores y lance excepciones tipadas:
class NueFormApiError extends Error {
constructor(code, message, status) {
super(message);
this.name = "NueFormApiError";
this.code = code;
this.status = status;
}
}
async function nueformRequest(path, options = {}) {
const response = await fetch(`https://app.nueform.io/api/v1${path}`, {
...options,
headers: {
"Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
"Content-Type": "application/json",
...options.headers,
},
});
const body = await response.json();
if (!response.ok) {
const { code, message, status } = body.error;
throw new NueFormApiError(code, message, status);
}
return body;
}
// Uso
async function getForm(formId) {
try {
const { data } = await nueformRequest(`/forms/${formId}`);
return data;
} catch (error) {
if (error instanceof NueFormApiError) {
switch (error.code) {
case "NOT_FOUND":
console.error(`Form ${formId} does not exist.`);
return null;
case "UNAUTHORIZED":
console.error("Check your API key configuration.");
break;
case "RATE_LIMITED":
console.warn("Rate limited. Implement backoff and retry.");
break;
default:
console.error(`API error [${error.code}]: ${error.message}`);
}
}
throw error;
}
}
Python
import os
import requests
class NueFormApiError(Exception):
def __init__(self, code, message, status):
super().__init__(message)
self.code = code
self.status = status
class NueFormClient:
def __init__(self, api_key=None):
self.api_key = api_key or os.environ["NUEFORM_API_KEY"]
self.base_url = "https://app.nueform.io/api/v1"
def request(self, method, path, **kwargs):
url = f"{self.base_url}{path}"
headers = {
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json",
}
response = requests.request(method, url, headers=headers, **kwargs)
body = response.json()
if not response.ok:
error = body["error"]
raise NueFormApiError(
error["code"], error["message"], error["status"]
)
return body
# Uso
client = NueFormClient()
try:
result = client.request("GET", f"/forms/{form_id}")
form = result["data"]
print(f"Form: {form['title']}")
except NueFormApiError as e:
if e.code == "NOT_FOUND":
print(f"Form {form_id} does not exist.")
elif e.code == "UNAUTHORIZED":
print("Check your API key configuration.")
elif e.code == "RATE_LIMITED":
print("Rate limited. Implement backoff and retry.")
else:
print(f"API error [{e.code}]: {e}")
Mejores prácticas
Siempre verifica el campo error
Nunca asumas que una respuesta es exitosa basándote únicamente en la presencia de un cuerpo. Siempre verifica el campo error o comprueba el código de estado HTTP antes de procesar la respuesta.
Usa códigos de error específicos para el flujo de control
Compara con error.code (por ejemplo, NOT_FOUND, RATE_LIMITED) en lugar del código de estado HTTP. Los códigos de error son estables, descriptivos y más fáciles de razonar en la lógica de la aplicación.
Registra los detalles del error
Incluye la respuesta de error completa en tus registros para depuración. El code, message y status juntos proporcionan suficiente contexto para diagnosticar la mayoría de los problemas sin reproducir la solicitud.
Maneja errores 5xx con reintentos
Los errores del servidor (500 Internal Error) son típicamente transitorios. Implementa lógica de reintento con retroceso exponencial para estas respuestas. Limita los reintentos a 2--3 intentos antes de fallar.
No expongas mensajes de error a los usuarios finales
Los mensajes de error de la API están diseñados para desarrolladores, no para usuarios finales. Mapea los errores de la API a mensajes amigables para el usuario en tu aplicación.
Si recibes respuestas 500 Internal Error persistentes, contacta con soporte proporcionando los detalles de la solicitud y las marcas de tiempo. Los errores del servidor se registran en nuestro sistema y se investigan.