Referencia
Errores y límites
Cada error con su código, repetir sin duplicar y qué hacer con un 429.
El formato
Todos los errores tienen la misma forma, con su código HTTP. fields va cuando falla un dato: cada campo, su code y su mensaje. Los code no cambian nunca; los mensajes, en el idioma de Accept-Language.
{ "error": { "code": "…", "message": "…", "fields": [{ "path": "…", "code": "…", "message": "…" }] } }code | HTTP | Cuándo |
|---|---|---|
unauthorized | 401 | Sin token, o con uno caducado o que no vale |
forbidden | 403 | El token no tiene el permiso de esa operación |
connection_revoked | 403 | La gestora retiró el permiso |
not_found | 404 | El centro, el trastero, la foto o la solicitud no son de esta conexión |
idempotency_key_reused | 409 | La misma Idempotency-Key con otro cuerpo |
facility_not_ready | 409 | Tamaños, trasteros, plano o fotos de un centro que aún no has mandado |
payload_too_large | 413 | Más de 5 MB de JSON, 2 MB por planta o 15 MB por foto |
unsupported_media_type | 415 | Una foto que no es JPEG, PNG ni WebP |
invalid_facility, invalid_unit_types, invalid_units, invalid_floor_plan, invalid_photo | 422 | Con fields: cada campo que falla |
rate_limited | 429 | Demasiadas peticiones, con Retry-After |
server_error | 500 | Es nuestro. Vuelve a probar con la misma Idempotency-Key |
Repetir sin duplicar
Manda Idempotency-Key (un UUID) en todo lo que cambia algo. Con la misma clave y el mismo cuerpo, durante 24 horas, la respuesta es la misma, con la cabecera Idempotent-Replayed: true. Con otro cuerpo, 409 idempotency_key_reused. Así puedes repetir sin miedo lo que no sabes si llegó.
Los límites
10 peticiones por segundo por cada permiso de gestora, con picos de 50. Si te pasas, 429 rate_limited con Retry-After (en segundos): espera ese tiempo y repite la petición con la misma Idempotency-Key.
| Qué | Hasta |
|---|---|
| Un JSON | 5 MB |
| Un plano | 2 MB por planta, 10 plantas |
| Una foto | 15 MB; 20 por centro |
| Centros en la lista de cada día | 2.000 |