No parece haber un estándar.
La respuesta de StackOverflow se inclina hacia 410 GONE, pero creo que 301 MOVIDO PERMANENTEMENTE es más apropiado.
Para tomar la decisión correcta, debemos analizar su caso específico. Si su objetivo es hacer que todas las llamadas realizadas a API v1 fallen sin tomar ninguna otra medida, 410 GONE funciona para eso. Si desea algo de continuidad, como redirigir al cliente a una versión más nueva de su API donde su llamada puede tener éxito, 3XX funciona, pero ¿cuál elige? Creo que si está intentando cerrar API v1, 301 MOVIDO PERMANENTEMENTE ayuda a indicar que es mejor que 303 VER OTRO porque 301 sugiere que todas las solicitudes futuras deben hacerse a la nueva url mientras que 303 no indica si esta situación es o no permanente.
Recomendaría diseñar la API de tal manera que cada versión siga siendo compatible con versiones anteriores, de modo que 301 MOVIDO PERMANENTEMENTE mantenga su API viva y actualizada de manera transparente cada vez que agregue nuevos puntos finales para nuevas versiones de API. Creo que eso es lo que estás tratando de hacer de todos modos.
Códigos de estado HTTP
El código de estado HTTP 302 era originalmente demasiado amplio y, por lo tanto, se implementó / usó incorrectamente, por lo que 303 y 307 se hicieron para distinguir entre el caso de uso dual de 302. Algunas API usan 303 para otros fines.
301 MOVIDO PERMANENTEMENTE - El código de estado 301 (Movido permanentemente) indica que al recurso objetivo se le ha asignado un nuevo URI permanente y cualquier referencia futura a este recurso debería usar uno de los URI adjuntos.
302 ENCONTRADO : el código de estado 302 (encontrado) indica que el recurso de destino reside temporalmente bajo un URI diferente. Debido a que la redirección puede ser alterada ocasionalmente, el cliente debe continuar usando el URI de solicitud efectivo para futuras solicitudes.
303 VER OTRO : una respuesta 303 a una solicitud GET indica que el servidor de origen no tiene una representación del recurso de destino que el servidor puede transferir a través de HTTP. Sin embargo, el valor del campo Ubicación se refiere a un recurso que es descriptivo del recurso de destino, de modo que realizar una solicitud de recuperación en ese otro recurso podría dar como resultado una representación útil para los destinatarios sin implicar que representa el recurso de destino original.
410 GONE : el código de estado 410 (Gone) indica que el acceso al recurso de destino ya no está disponible en el servidor de origen y que es probable que esta condición sea permanente. Si el servidor de origen no sabe, o no tiene facilidad para determinar, si la condición es permanente o no, debe utilizarse el código de estado 404 (No encontrado).
¿Cómo manejan esto las API existentes?
Tal vez pueda tomar una página de la API de Youtube de Google :
Cuando falla una solicitud de API, YouTube devolverá un código de respuesta HTTP 4xx o 5xx que identifica genéricamente la falla, así como una respuesta XML que proporciona información más específica sobre los errores que causaron la falla. Para cada error, la respuesta XML incluye un elemento de dominio, un elemento de código y posiblemente un elemento de ubicación.
Otras lecturas: