Errores y límites
Netzo rechaza una solicitud con el mismo error en toda superficie. El error dice qué pasó y qué hacer, así una persona o un agente lo corrigen sin adivinar.
Qué trae un error
| Campo | Contiene |
|---|---|
status | El estado HTTP: 403, 409, 422… |
code | Un código estable, como rpc.RECORD_LOCKED. Úsalo en tu código; no compares el mensaje. |
message | Qué pasó, en el idioma de quien llama |
fix | El siguiente paso para corregirlo |
fields | Los campos que causaron el rechazo, cuando aplica |
retryable | Si reintentar la misma solicitud puede funcionar |
El idioma sigue el encabezado Accept-Language (es o en), igual en la API, MCP y la CLI.
Clases de error
| Estado | Significa | Códigos comunes | Qué hacer |
|---|---|---|---|
401 | Falta la credencial o no es válida | UNAUTHENTICATED | Envía una credencial válida. Ve Autenticación |
403 | La credencial no tiene el permiso | FORBIDDEN, FIELD_FORBIDDEN, APPROVAL_REQUIRED | Pide el permiso, o la aprobación. Revisa antes con can |
404 | El registro no existe o no lo puedes ver | NOT_FOUND | Revisa el id y el lugar |
409 | El cambio choca con el estado o con una regla | INVARIANT_VIOLATED, RECORD_LOCKED, IDENTIFIER_NOT_UNIQUE, CONCURRENT_UPDATE | Lee fix. Ve Reglas e integridad |
412 | Una aprobación falta o sigue pendiente | APPROVAL_PENDING, APPROVAL_REQUEST_MISSING | Espera la aprobación. Ve Accesos |
422 | La entrada no es válida | — | Corrige los campos de fields |
429 | Demasiadas solicitudes | TOO_MANY_REQUESTS | Espera lo que dice Retry-After |
Una regla de una tabla tiene su propio código y su mensaje ya dice cómo corregirla, por ejemplo "El periodo fiscal está cerrado".
Reintentos
Reintenta solo cuando retryable es true. CONCURRENT_UPDATE significa que otra solicitud cambió el registro primero: vuelve a leerlo y repite el cambio. Cualquier otro error se repite igual hasta que corrijas la causa.
Para no duplicar un registro al reintentar, busca antes por su clave de negocio. Ve API.
Por superficie
| Superficie | Cómo llega el error |
|---|---|
| API | El estado HTTP, con el error en el cuerpo JSON |
| MCP | Un error de la herramienta con el mensaje, fix y los campos |
| CLI | El error en la salida de error y un código de salida estable. Ve CLI |
| App | Un aviso con el mensaje y la corrección, junto al campo cuando aplica |
Límites
| Límite | Valor |
|---|---|
| Solicitudes a la API y MCP | 1,200 por minuto por credencial: cada clave API, cada persona con OAuth y cada persona con sesión tiene su propio límite |
| Vigencia de una clave API | 90 días si no eliges otra fecha; a lo más 365 |
| Entrega de un webhook | 10 segundos por intento, hasta 3 reintentos. Ve Webhooks |
Una solicitud sobre el límite recibe 429 y el encabezado Retry-After con los segundos que faltan.