AyudaAPIErrores y límites

Errores y límites

Cada código de error de la API pública, la tabla de límites por plan, y qué pasa cuando los superas.

Una sola forma de error, un solo lugar para consultar cada código.

Todo fallo de /api/v1 responde con la misma forma de cuerpo:

{
  "error": "TEMPLATE_NOT_FOUND",
  "message": "No Template with this id exists for this account."
}

Decide según el campo error, nunca según el texto del mensaje — el mensaje es para una persona leyendo registros, no para que tu código lo interprete.

Todos los códigos de error

Código	Estado	Mensaje
`API_KEY_INVALID`	401	The API Key is malformed, unknown, revoked, or its account is inactive.
`API_KEY_MISSING`	401	Send the API Key as an `Authorization: Bearer` header.
`CONCURRENCY_LIMIT_REACHED`	429	This account already has the maximum number of Runs in flight for its plan.
`EXPORT_LIMIT_REACHED`	402	This account has used its Quota for the current billing period.
`FILE_TOO_LARGE`	413	The uploaded file exceeds this plan's upload size ceiling.
`IDEMPOTENCY_KEY_REUSED`	409	This `Idempotency-Key` was already used for a different request.
`INSUFFICIENT_SCOPE`	403	The API Key does not carry the scope this operation requires.
`INVALID_IDEMPOTENCY_KEY`	422	`Idempotency-Key` must be 1-255 printable characters.
`INVALID_PARSE_PARAMS`	422	`delimiter` must be one printable character; `header_row` must be a non-negative integer within the row ceiling.
`MALFORMED_FILE`	400	The file could not be read: it is empty, corrupt, or not encoded as expected.
`NO_SUBSCRIPTION`	403	This account has no active subscription.
`RATE_LIMITED`	429	This account has exceeded its request rate limit for this operation.
`ROW_LIMIT_EXCEEDED`	413	The uploaded file exceeds this plan's row ceiling.
`RUN_NOT_FOUND`	404	No Run with this id exists for this account. Runs are kept 30 minutes and are lost if the service restarts.
`SERVER_BUSY`	503	This worker is at its memory budget; retry shortly.
`TEMPLATE_COLUMNS_MISSING`	422	The uploaded file is missing one or more columns this Template's operations require.
`TEMPLATE_NOT_FOUND`	404	No Template with this id exists for this account.
`UNSUPPORTED_FILE_TYPE`	415	This file type is not supported.

Cuota y concurrencia

Superar las ejecuciones mensuales de tu plan responde 402 EXPORT_LIMIT_REACHED, con un objeto quota (usado, límite, cuándo se reinicia). Iniciar más ejecuciones a la vez de las que permite la concurrencia de tu plan responde 429 CONCURRENCY_LIMIT_REACHED. Enviar solicitudes más rápido de lo que permite el ritmo de tu cuenta responde un segundo código, distinto, 429 RATE_LIMITED. Un worker en su límite de memoria responde 503 SERVER_BUSY— reintenta en breve.

Toda respuesta de /api/v1 lleva las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset para la ventana con la que se comprobó esa solicitud, para que un script pueda frenar antes de que lo rechacen.

Lo que no cuesta nada

Listar plantillas y consultar el estado o el resultado de una ejecución nunca gastan tu cuota mensual. Solo cuenta una ejecución que termina y devuelve un archivo — una rechazada, fallida, expirada por tiempo, interrumpida o reproducida de forma idempotente nunca se cobra.

Límites por plan

Plan	Filas por archivo	Ejecuciones al mes	Plantillas	Archivos unidos al mes	Ejecuciones simultáneas
Free	5,000	5	2	0	1
Pro	100,000	50	10	5	2
Business	500,000	Ilimitado	Ilimitado	Ilimitado	3
Enterprise	1,000,000	Ilimitado	Ilimitado	Ilimitado	5

El detalle completo de cada plan está en la página de precios.