Errors

Error Response Format

All API errors return a JSON object with an error field:

{
  "error": "Human-readable error message"
}

Some errors may include an optional code field for programmatic handling:

{
  "error": "Correo ya registrado",
  "code": "DUPLICATE_EMAIL"
}

ℹ️

Error messages from the API are returned in Spanish, as the platform targets Spanish-speaking users. This reference explains what each message means.

HTTP Status Codes

Status	Meaning	Common Causes
`400`	Bad Request	Validation error — missing or invalid fields
`401`	Unauthorized	Not authenticated — session cookie missing or expired. API returns: `"No autorizado"`
`403`	Forbidden	Insufficient role permissions or plan-gated feature on FREE plan. API returns: `"Sin permisos"` or `"Función disponible en el plan Pro"`
`404`	Not Found	Resource doesn't exist or belongs to a different tenant
`409`	Conflict	Duplicate value — email, SKU, or other unique field already exists
`502`	Bad Gateway	Webhook delivery failed — could not connect to endpoint

Validation Errors (400)

Request bodies are validated using Zod schemas. When validation fails, the API returns the first validation error message (in Spanish):

{
  "error": "El nombre es requerido"
}

Common validation errors:

Field	Error (Spanish)	Meaning
Missing required field	`"El nombre es requerido"`	Name is required
Invalid email	`"Correo electrónico inválido"`	Invalid email address
Invalid URL	`"URL inválida"`	Invalid URL
Number out of range	`"El precio debe ser mayor a 0"`	Price must be greater than 0

Authentication Errors (401)

Returned when no valid session is found:

{
  "error": "No autorizado"
}

This means "Not authorized" in Spanish. Fix: Ensure you include the next-auth.session-token cookie. See the Authentication guide.

Permission Errors (403)

Returned in two cases:

Insufficient role permissions:

{
  "error": "Sin permisos"
}

This means "No permissions" in Spanish. The authenticated user's role doesn't have the required permission. See the permission matrix.

Plan-gated feature:

{
  "error": "Función disponible en el plan Pro"
}

This means "Feature available on the Pro plan" in Spanish. The feature requires a PRO plan. Upgrade your plan to access it.

Not Found (404)

Returned when a resource doesn't exist or belongs to a different tenant:

{
  "error": "Cotización no encontrada"
}

This means "Quote not found" in Spanish. Since the API enforces tenant isolation, you'll get a 404 (not 403) when trying to access another tenant's resources.

Conflict (409)

Returned when a unique constraint would be violated:

{
  "error": "Ya existe un producto con ese SKU"
}

This means "A product with that SKU already exists" in Spanish.

Best Practices

Always check the status code — don't assume success
Parse the error field — it contains a human-readable message (in Spanish) suitable for display to end users
Handle 401 by re-authenticating — session cookies expire
Handle 403 by checking role/plan — not all users can access all endpoints
Handle 400 by showing the validation message — it tells the user exactly what to fix

PreviousAuthentication NextWebhooks