Errors

Jelliu uses conventional HTTP status codes and returns every error in the same JSON envelope:

{
  "error": {
    "code": "CAMPAIGN_NOT_ACTIVE",
    "message": "Campaign can only be activated from DRAFT or PAUSED status"
  }
}

Messages are for people, codes are for code

Messages are written for the person reading them, and the language depends on the endpoint. Jelliu’s customers are Spanish-speaking, so many product-facing messages are in Spanish, while others are in English. Both of these are real responses:

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Servicio no disponible temporalmente. Vuelve a intentarlo en unos segundos."
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests, please slow down"
  }
}

HTTP status codes

For 5xx responses the real cause is logged on our side and never returned. The body carries a generic message: Internal server error, or An unexpected error occurred with code INTERNAL_ERROR.

Common error codes

The status shown is the usual one. A few codes are returned with a different status on specific endpoints (for example VALIDATION_FAILED with 409 or 422), so read the status and the code together.

Validation errors

Validation failures return 400 with code VALIDATION_FAILED and a details field. Depending on the endpoint, details takes one of two shapes.

Field map. Most create and update endpoints report errors grouped by field:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid campaign input",
    "details": {
      "formErrors": [],
      "fieldErrors": {
        "agentId": ["Invalid uuid"],
        "productContext": ["String must contain at least 10 character(s)"]
      }
    }
  }
}

Issue list. Other endpoints return a flat list of issues, each with a dotted path:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": [
      { "path": "url", "message": "Invalid url", "code": "invalid_string" }
    ]
  }
}

No details. Some input problems are caught outside the endpoint’s own validation and come back as VALIDATION_FAILED with only a Spanish message:

These requests used to fail with 500 INTERNAL_ERROR. Fix the value and send the request again.

Size limits

A JSON or form body larger than 1 MB, or an uploaded file larger than the route’s limit (20 MB for knowledge documents, 10 MB for a web chat attachment), is refused with 413:

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "El cuerpo de la petición es demasiado grande."
  }
}

An oversized file gets El archivo es demasiado grande para esta operación. A few routes answer their own size errors instead: the CSV contact upload returns 400 VALIDATION_FAILED (Uploaded file is too large (max 10MB).), and a web chat attachment checked after upload returns the widget’s own 413 body. Do not retry a 413 unchanged: split the batch or shrink the file.

Metadata

metadata is included only for the four codes below, and only with keys from a fixed allowlist. Everything else stays server-side. The keys you will typically see:

No active subscription

A workspace whose subscription is not active, trialing or past_due is refused some features with 403 BILLING_ERROR, metadata.tier: "none" and metadata.kind: "subscription_required". Use kind to tell this apart from a plan that lacks a feature, and send the user to choose a plan. The message names the feature:

{
  "error": {
    "code": "BILLING_ERROR",
    "message": "«Servidores MCP» requiere una suscripción activa. Este espacio de trabajo no tiene un plan activo: elige uno en Ajustes → Plan para continuar. Tus datos siguen disponibles para consultar y exportar.",
    "metadata": { "tier": "none", "kind": "subscription_required" }
  }
}

Retrying does not help until the workspace subscribes. Reading and exporting your own data is not affected. The list of refused operations is in Billing and usage.

Retrying

• Retry 429 and 503 after the number of seconds in the Retry-After header.
• 409 AGENT_PROVISIONING also carries Retry-After.
• Other 4xx errors, including 413, will fail again until the request, the key or the resource state changes.
• For other 5xx errors, retry with exponential backoff.