Convenciones
Valen para toda la API, así que no se repiten en cada endpoint.
Paginación
Los listados aceptan page (desde 1) y limit (20 por defecto, 100 máximo), y responden con total, page, limit y data. El orden es por fecha de creación descendente, así que paginar es estable.
Errores
Todo error trae error (código estable) y message (texto legible). Un 400 de validación agrega issues, con el campo exacto que se rechazó.
Límites de tasa
120 lecturas y 30 escrituras por minuto. Al excederlo la respuesta es 429 con la cabecera Retry-After en segundos, y cada respuesta trae X-RateLimit-Remaining.
Alcance
La apiKey opera sobre toda la cuenta: la de un sub-usuario ve los mismos lotes y análisis que la del dueño. Nunca alcanza los datos de otra cuenta.
Forma de una respuesta paginada
{
"total": 42,
"page": 1,
"limit": 20,
"data": [ /* … */ ]
}Forma de un error de validación
{
"error": "VALIDATION_FAILED",
"message": "Invalid request body",
"issues": [
{ "path": "mapResolution", "message": "Invalid input" }
]
}Sobre /api/v0 POST /api/v0/analyses sigue funcionando y no va a dejar de hacerlo, pero está deprecado: usa POST para una lectura, no ordena los resultados y sus filtros no se combinan. Para código nuevo, usá GET /api/v2/analyses.