Respuestas de error

Para desarrolladores

La plataforma responde todos los errores con el mismo formato: RFC 9457 application/problem+json. Para decidir cómo reaccionar ante un error, use el campo code (un identificador que no cambia, pensado para que lo lea su sistema), no el texto de detail.

Campos del error

Campos del body de error:

Campo	Tipo	Presencia	Significado
type	string (URI)	siempre	URL de la documentación del error: https://docs.fidelizador.com/errors/<code>, con el code escrito con guiones en lugar de guiones bajos.
title	string	siempre	Frase HTTP del status (Conflict, Not Found, ...).
status	number	siempre	Código HTTP, repetido en el body.
detail	string	siempre	Mensaje de respaldo, en inglés. Es descriptivo en 402, 404, 409 y 422, y genérico en 401, 403 y 5xx, donde no se informa el motivo. Para mostrar mensajes traducidos, derívelos de code.
code	string	siempre	Identificador estable del error, independiente del status y del type. Úselo para distinguir un error de otro.
trace_id	string	siempre	ID de traza para correlación. Útil al reportar un problema a soporte.
errors	array	solo 422	Lista de errores por campo (ver Errores por campo).

Campos adicionales: algunos errores agregan campos propios en el nivel superior de la respuesta (p. ej. limit y upgrade_url en el 402 del plan). Un cliente debe ignorar los campos que no conoce.

Ejemplo (401):

{
  "type": "https://docs.fidelizador.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication required.",
  "code": "unauthorized",
  "trace_id": "dbb56202f13e1c15473bc6044ede8539"
}

Toda respuesta, de éxito o de error, lleva además el header X-Request-Id, y a veces X-Trace-Id. El identificador del request no viene en el body. Los headers y el formato de las respuestas exitosas están en Paginación y formato de respuesta.

Tabla resumen

El sufijo de type es siempre el code con guiones.

17 de 17

400Request mal formado1 código

bad_request		Request mal formado (query/body inválido).

401No autenticado1 código

unauthorized		Credencial ausente, inválida o expirada, o X-Instance-Slug inexistente. Revise la API key y el slug.

402Límite de plan o suscripción3 códigos

plan_send_limit_exceeded		Enviar supera la cuota de envíos del plan para el período vigente (incluye limit/remaining/reset_at).
plan_webhooks_limit_exceeded		Crear un webhook supera el cupo de webhooks del plan.
subscription_inactive		La cuenta no tiene una suscripción activa o válida, o el plan no incluye envíos. Si al plan le falta otra funcionalidad, se devuelve el código de esa funcionalidad.

403Sin permiso2 códigos

forbidden		Sin permiso: scope, rol, o instancia deshabilitada.
ip_not_allowed		La dirección de origen no está en la lista de IPs permitidas de la instancia o en la de la API key.

404Recurso no encontrado2 códigos

<recurso>_not_found (not_found solo en ruta inexistente)		El recurso no existe.
mail_outside_retention		El mail_id consultado es anterior a la ventana de retención en línea.

405Método no permitido1 código

method_not_allowed		Verbo HTTP incorrecto.

409Conflicto1 código

<regla> (p. ej. sandbox_relay_restricted)		Violación de unicidad o regla de negocio. El code siempre es específico.

413Request demasiado grande1 código

request_too_large		El request supera algún límite de tamaño (body, descompresión, adjunto, mensaje o ancho de banda).

415Media type no soportado1 código

unsupported_media_type		Content-Type no soportado.

422Validación fallida1 código

validation_error		Falla de validación de esquema (incluye errors[]).

429Rate limit excedido1 código

rate_limit_exceeded		Límite de ancho de banda de la instancia. Espere los segundos indicados en el header Retry-After antes de reintentar.

500Error interno1 código

internal_error		Error no manejado. El detail es un texto genérico.

503Servicio no disponible1 código

service_unavailable		Una dependencia no respondió.