Errors & Rate Limits

Formato de errores, codigos HTTP y limites / Error format, HTTP codes, and limits

Error Format

All API errors return JSON with this structure:

json

{
  "error": "Human-readable error message",
  "errors": ["Optional array of field-level details"],
  "code": "OPTIONAL_MACHINE_READABLE_CODE"
}

The errors array is only present on 400 validation errors. It contains specific details about which fields failed validation.

The code field is optional and present on some 403 responses (plan limit reached, account inactive) and on the 429 monthly-capacity response. It's a stable, machine-readable identifier you can switch on in your integration instead of parsing the error message. Values come from ErrorCode in lib/domain/errors.ts:

El campo code es opcional y aparece en algunas respuestas 403 (limite de plan alcanzado, cuenta inactiva) y en el 429 de capacidad mensual. Es un identificador estable para tu integracion, en vez de parsear el mensaje.

Code	Status	Meaning
`FORM_LIMIT_REACHED`	403	Plan's max number of forms reached
`QUESTION_LIMIT_REACHED`	403	Plan's max questions-per-form reached
`AI_GENERATION_LIMIT_REACHED`	429	Plan's monthly AI generation quota reached
`CONVERSATION_LIMIT_REACHED`	403	Plan's monthly conversation quota reached
`SUBSCRIPTION_INACTIVE`	403	Form owner's subscription is not active
`FEATURE_NOT_AVAILABLE`	403	Feature (e.g. pipelines) not available on this plan
`PIPELINE_LIMIT_REACHED`	403	Plan's max number of pipelines reached
`DEAL_LIMIT_REACHED`	403	Plan's max number of deals reached

HTTP Status Codes

Status	Meaning	When it happens
200	OK	Successful request
201	Created	Resource created (new form, new webhook config)
400	Bad Request	Validation failure, missing fields, wrong form type
401	Unauthorized	Not authenticated (session expired/missing, or invalid API key)
403	Forbidden	Domain not allowed, plan limit reached, account inactive
404	Not Found	Resource doesn't exist, form not published
500	Internal Server Error	Unexpected server error
502	Bad Gateway	Webhook delivery failed (test endpoint only)

Common Errors

Public endpoints

Error	Status	Cause & solution
`Form not found`	404	Form doesn't exist or is not published
`Domain not allowed`	403	Add your domain to the form's Allowed Domains
`Account inactive`	403	The form owner's subscription has expired
`Classic forms do not support chat`	400	Use `/api/forms/:id/submit` for CLASSIC forms
`This endpoint is only for classic forms`	400	Use `/api/chat` for CONVERSATIONAL forms
`Missing required field: {field}`	400	A required question was not answered
`Invalid data`	400	Request body doesn't match the expected schema

Authenticated endpoints

Error	Status	Cause & solution
`Unauthorized`	401	Session cookie missing/expired, or the API key is invalid. Log in again or check your `Authorization: Bearer rvk_...` header
`Form with id "{id}" not found`	404	Form doesn't exist or you don't own it
Plan limit error	403	Upgrade your plan to create more forms (`code` identifies the limit)

Plan Limits

Los limites dependen del plan del usuario / Limits depend on the user's plan.

Resource	FREE	PRO	BUSINESS
Forms	1	10	Unlimited
Conversations / month	100	500	2,500
Webhooks	No	Yes	Yes
Email notifications	No	Yes	Yes

When a per-form/plan resource limit is reached the API returns 403; the monthly conversation cap returns 429 (code: CONVERSATION_LIMIT_REACHED).

Pagination

All list endpoints use consistent pagination:

Request parameters:

Param	Type	Default	Max	Description
`page`	number	1	-	Page number
`limit`	number	10	100	Items per page

Response format:

json

{
  "items": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5
  }
}

The actual items key varies by endpoint (forms, conversations, etc.).

Rate Limits

Rate limiting is not yet enforced. When implemented, the following limits will apply:

Endpoint	Limit	Scope
`POST /api/chat`	20 requests / minute	Per IP
`POST /api/forms/:id/submit`	10 requests / minute	Per IP
`POST /api/forms/generate`	5 requests / minute	Per user

Rate-limited requests will return 429 Too Many Requests.