# Solicitudes

Envía JSON en el cuerpo de la solicitud.

```
Content-Type: application/json
```

Los identificadores son UUID. `workspaceId` es obligatorio en las listas que no quedan ya acotadas por un id en la ruta. Las fechas son ISO-8601 en UTC.

## Respuestas

Cada respuesta usa el mismo sobre. `data` es `null` cuando la llamada falla. `error` es `null` cuando tiene éxito.

```json
{
  "success": true,
  "data": {},
  "error": null
}
```

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "workspaceId is required."
  }
}
```

`error.details` aparece en los fallos de validación y lista los campos que fallaron.

## Errores

| Estado | Código | Significado |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Falta un campo obligatorio o hay un valor inválido |
| 401 | — | El token Bearer falta, es desconocido o fue revocado |
| 403 | — | La clave no incluye el alcance requerido |
| 404 | — | El registro no existe en este espacio de trabajo |
| 429 | `RATE_LIMIT_EXCEEDED` | El espacio agotó su cupo mensual de la API |

Trata cualquier `success: false` como un fallo, también un `2xx` que no esperabas. Reintenta el `429` cuando se reinicie la ventana mensual. No reintentes un `401` o un `403` con la misma clave.

## Cupo

Cada clave de API cuenta contra el cupo mensual de solicitudes del plan del espacio. Cuando se agota, la API responde `429` con `RATE_LIMIT_EXCEEDED`. Leer la analítica y entregar webhooks entra en el mismo cupo.

## Publicar un reproductor

`PATCH /v1/player-config/{playerId}/draft` no cambia el embed. `POST /v1/player-config/{playerId}/publish` copia el borrador al reproductor en vivo e incrementa `publishedVersion`. Un reproductor recién creado tiene `publishedVersion` `0` hasta la primera publicación.

La carga de un vídeo tiene dos pasos. `POST /v1/videos` crea el registro. `POST /v1/videos/{videoId}/upload-url` devuelve el destino de carga de un solo uso. Consulta `GET /v1/videos/{videoId}/status` hasta que `status` sea `ready`.
