Jelliu API documentation

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"
  }
}

Field	Always present	Description
`error.code`	Yes	Stable, machine-readable identifier. Branch on this.
`error.message`	Yes	Human-readable explanation. May change at any time.
`error.details`	Only on `VALIDATION_FAILED`	Which fields failed and why. See Validation errors.
`error.metadata`	Only on a few codes	Structured context, such as plan limits. See Metadata.

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": "BILLING_ERROR",
    "message": "Campaign limit reached (3 campaigns on the growth plan). Upgrade your plan in Settings → Plan.",
    "metadata": { "limit": 3, "current": 3, "tier": "growth" }
  }
}

Never parse or match message. It is not translated consistently and can be reworded without notice. Switch on error.code and the HTTP status.

HTTP status codes

Status	Meaning
`400`	The request is malformed or failed validation.
`401`	Missing, malformed, unknown, revoked or expired API key.
`402`	A plan limit was exceeded (`PLAN_LIMIT_EXCEEDED` on some routes).
`403`	Authenticated but not allowed: scope, role, plan feature, compliance rule or suspended workspace.
`404`	The resource does not exist or belongs to another workspace.
`409`	The request conflicts with the resource’s current state.
`422`	The request is well-formed but semantically invalid (used by a few endpoints).
`429`	Rate limit, concurrency limit or budget exhausted. Honor `Retry-After`.
`500`	Unexpected server error.
`502`	An upstream provider failed (for example an integration sync).
`503`	A temporary infrastructure problem. Safe to retry after `Retry-After`.

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.

Code	Status	When
`VALIDATION_FAILED`	400	Body, query or path parameters failed validation.
`UNAUTHORIZED`	401	See Authentication.
`FORBIDDEN`	403	The key’s scope or the route’s role requirement does not allow the request.
`TENANT_SUSPENDED`	403	The workspace is suspended.
`BILLING_ERROR`	403 (usually)	The plan does not include the feature or channel, or a resource cap (agents, campaigns, contacts, integrations) was reached.
`COMPLIANCE_BLOCKED`	403	Blocked by compliance rules or content screening.
`PHONE_NUMBER_REQUIRED`	403	Outbound calling needs a phone number owned by the workspace.
`NOT_FOUND`	404	Generic not found.
`AGENT_NOT_FOUND`, `CAMPAIGN_NOT_FOUND`, `CALL_NOT_FOUND`, `CONVERSATION_NOT_FOUND`	404	The specific resource was not found in your workspace.
`CAMPAIGN_NOT_ACTIVE`	400 or 409	The campaign is not in a state that allows the transition.
`PLAN_LIMIT_EXCEEDED`	402 or 409	A hard limit was reached, such as 25 active API keys.
`CALL_ALREADY_IN_PROGRESS`	409	The same operation is already running, for example a number being provisioned. Retry shortly.
`AGENT_PROVISIONING`	409	The agent is still being set up. Retry after `Retry-After` (5 seconds).
`AGENT_PAUSED`	409	The agent has been stopped in the dashboard. `503` if its state could not be checked.
`AGENT_CHANGE_PENDING_APPROVAL`	409	The change was held for review and not applied.
`AGENT_ACTION_PENDING_APPROVAL`	409	The action is waiting for a person to approve it and did not run.
`AGENT_ACTION_APPROVAL_CLOSED`	409	The approval request already expired or was decided.
`NUMBER_UNVERIFIED`	400	The telephony account can only call verified numbers.
`RATE_LIMIT_EXCEEDED`	429	See Rate limits.
`MAX_CONCURRENT_CALLS_REACHED`	429	The concurrency limit for calls was reached.
`AGENT_BUDGET_EXCEEDED`	429	The agent used up the action or spend budget set by the workspace.
`AI_WEEKLY_CAP_REACHED`	429	The weekly budget for an in-product AI feature is used up.
`INTEGRATION_SYNC_FAILED`	502 (usually)	A connected integration or upstream provider failed.
`INTERNAL_ERROR`	500	Unexpected error.
`SERVICE_UNAVAILABLE`	503	Temporary infrastructure problem. `Retry-After: 5`.

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" }
    ]
  }
}

Handle both: if details is an array, read path and message from each item; if it is an object, read fieldErrors.

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:

Code	Typical keys
`BILLING_ERROR`	`limit`, `current`, `tier`, `upgradeTo`
`AI_WEEKLY_CAP_REACHED`	`kind`, `tier`, `weekStart`, `limitTokens`, `upgradeTo`
`AGENT_CHANGE_PENDING_APPROVAL`	`changeRequestId`, `fields`
`AGENT_ACTION_PENDING_APPROVAL`	`requestId`, `expiresAt`, `reversibility`, `match`

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 will fail again until the request, the key or the resource state changes.
For other 5xx errors, retry with exponential backoff.