Errores y solución de problemas

El saldo no cubre esta llamada. Se chequea antes de ejecutarla, al precio completo, así que no se hace trabajo (ni se paga a un tercero) para una llamada que termina en 402. price es lo que cuesta, balance el saldo actual y shortfall lo que falta; los créditos van como texto. hint aparece solo si el saldo todavía cubre una ficha DAT-FREE: esa lectura sigue respondiendo. Si otro request gastó el saldo mientras esta llamada corría, el gateway relee la billetera: si esa lectura falla, balance y shortfall no vienen; si encuentra que el saldo ya alcanza (entró una recarga), shortfall no viene y el mensaje pide reintentar. Una llave con saldo cero no recibe este error: pasa al nivel gratuito (abajo).

La llamada llevaría el gasto del mes por encima del tope que fijó el dueño de la cuenta en Facturación. limit es el tope, consumed lo gastado en el período (un período vencido cuenta desde 0) y price lo que cuesta la llamada. resets_at es el primer día del mes siguiente (UTC) y la cabecera Retry-After trae los segundos hasta entonces. settings_url lleva a la sección de Facturación donde se sube o se quita el tope.

La llave gratuita venció: dura 90 días sin compra. Cualquier compra (Sandbox US$95 en adelante) la vuelve permanente; una llave vencida se reemplaza creando otra desde el Panel.

Una llave sin saldo pidió un código fuera del nivel gratuito (CHK-BIN, DAT-RESOLVE, DAT-FREE), una búsqueda, o un activo por id (pa_finca_, pa_ph_, pa_nave_, pa_marca_, pa_imp_…). Solución: pedir ?include=DAT-FREE o cargar saldo. Con ?dry_run=1 la misma llamada cotiza sin candado: conserva el precio en créditos y trae free_tier.locked: true.

La llamada no cabe en el cupo de la llave gratuita: 30 entidades/día o 500/mes (100/día y 1,000/mes con dominio corporativo). Cuentan cada fila cobrable de resolve (las invalid no), cada ficha DAT-FREE o CHK-BIN y cada id de /entities/batch; dry_run y el estimador no cuentan; un dry_run de la misma llamada trae free_tier.would_exceed: true y would_status: 429 antes de gastarla. Se emite solo cuando used + filas > limit: used, remaining y requested dicen cuánto queda (un lote de 7 sí pasa con 23/30), la cabecera Retry-After trae los segundos hasta el reinicio. Los contadores se cortan por día y mes UTC: reset_at es la próxima medianoche UTC (period: day) o el próximo día 1 a las 00:00 UTC (period: month).

POST /v5/resolve/batch con más de 10 filas desde una llave gratuita sin with_presence (el body se valida antes que el cupo: un lote de 11 a 23/30 es este 400, no un 429). Solución: lotes de 10, o with_presence: true para el estimador (solo agregados; hasta 100 filas; 5,000 filas/mes, 402 estimator_rows_exhausted al agotarse).

POST /v5/resolve con un ruc o una cedula cuyo formato no se reconoce (los identificadores se normalizan antes: espacios, «DV», minúsculas). En POST /v5/resolve/batch la misma fila no rompe el lote: sale con outcome: invalid, no se cobra ni cuenta.

Sin llave solo responden POST /v5/resolve (una fila) y GET /v5/entities/{id}. El lote, los sub-recursos, las búsquedas y las rutas v4 exigen una llave; la gratuita alcanza.

El nivel 0 agotó el presupuesto compartido del día (1,000 consultas para todo el nivel: HTTP directo + MCP público). Se reinicia a medianoche de Panamá (America/Panama, UTC−5), no en UTC; reset_at lo dice en ISO 8601. Una llave gratuita tiene su propio cupo y no lo siente.

GET /v5/entities/{id}?inline_limit=N con N fuera de 1..100 o no entero. El parámetro acota las listas inline de cada sección del detalle (default 10, DETAIL_INLINE_LIMIT); vale para cualquier nivel.

OpenSearch estaba caído, se agotó el tiempo, rechazó por carga (429 / es_rejected_execution) o respondió a medias (shards fallidos o timed_out). En una búsqueda de una sola superficie, que falte su índice también es este 502. Solución: reintentar después de los segundos que indica la cabecera Retry-After (5). POST /v5/resolve/batch reintenta una vez la fila que recibió un rechazo por carga; si vuelve a fallar, o si hay un timeout o una respuesta parcial, el 502 es de toda la llamada y no se cobra nada.

OpenSearch rechazó la consulta por su forma, típicamente un valor de filtro del tipo equivocado ({"monto_min": "abc"}, un array donde va un término). Solución: corregir la consulta; repetirla igual falla igual. En POST /v5/resolve/batch no rompe el lote: esa fila vuelve con outcome: invalid y no se cobra.

La respuesta de OpenSearch llegó y el gateway no la pudo leer: un bug de nuestro lado. No se cobra y reintentar la misma petición no ayuda; si persiste, contáctenos con la hora y la ruta.