Errore 404 sull'endpoint liquidatePosition dell'API Tradovate

Vuole chiudere una posizione da codice, quindi invia una richiesta POST all'endpoint liquidate aspettandosi una chiusura pulita. Invece il server restituisce 404 Not Found. Il suo token è valido, le altre chiamate di ordine funzionano, il JSON sembra perfetto, eppure proprio questa route si comporta come se non esistesse. È frustrante, perché sembra che l'endpoint sia rotto o mancante.

Non lo è. Un 404 è più circoscritto di quanto sembri: non riguarda il suo account, la sua posizione o il suo payload. Significa che l'URL esatto a cui ha inviato il POST non corrisponde a nessuna route sul server di Tradovate. Nove volte su dieci si tratta di una di queste tre cose: il percorso ha maiuscole/minuscole errate o è scritto male, sta puntando all'host sbagliato, oppure ha inviato il verbo HTTP sbagliato. Le escludiamo in ordine, per poi fissare la chiamata corretta e permetterle di chiudere la posizione in modo pulito.

Cosa le sta dicendo davvero un 404

Ogni errore HTTP indica un livello diverso, e confonderli porta a modificare la cosa sbagliata. Un 404 significa che il percorso non esiste. Un 401 significa che il percorso esiste ma non era autorizzato. Un 400 significa che percorso e autenticazione erano corretti ma il corpo della richiesta era malformato. Un 429 significa che sta raggiungendo il limite di frequenza delle richieste. Quindi, se ha davanti un 404 reale, smetta di modificare il corpo JSON: il server non è mai arrivato abbastanza avanti da occuparsene. Non è nemmeno riuscito a trovare la route.

Questo singolo fatto restringe molto la ricerca. Tutto ciò che produce un 404 si trova nella riga della richiesta: il metodo, l'host, il segmento di versione e la grafia del percorso. Verifichi questi quattro punti e l'errore sparirà.

Causa 1: il percorso ha maiuscole/minuscole errate o è scritto male

Questo è il grande classico, e coglie quasi tutti almeno una volta. I percorsi REST di Tradovate distinguono tra maiuscole e minuscole. L'operazione si scrive esattamente liquidatePosition, con la l minuscola e la P maiuscola in camelCase. Se la scrive in un altro modo, il router non ha nulla da far corrispondere e risponde con 404. Scrivere tutto in minuscolo è l'errore classico, di solito perché l'ha digitata a memoria o perché il suo framework ha normalizzato l'URL al posto suo.

La soluzione è poco entusiasmante ma affidabile: copi il nome dell'operazione direttamente dal riferimento API e lo incolli, invece di ridigitarlo. Basta un solo carattere sbagliato nelle maiuscole/minuscole. Già che c'è, controlli che non ci sia una barra finale accidentale o un segmento duplicato come /order/order/liquidatePosition che un generatore di URL può introdurre di nascosto.

Causa 2: host sbagliato o segmento di versione mancante

L'URL completo ha quattro parti che devono essere tutte corrette: schema, host, il segmento di versione /v1 e il percorso. Mettendoli insieme si ottiene:

• Demo/simulazione: https://demo.tradovateapi.com/v1/order/liquidatePosition
• Live: https://live.tradovateapi.com/v1/order/liquidatePosition

Se omette /v1 otterrà un 404, perché alla radice dell'API non è collegata direttamente nessuna route /order/liquidatePosition. Un errore di battitura nell'host produce lo stesso risultato, oppure fa fallire del tutto la risoluzione DNS. E non si rivolga qui all'host dei dati di mercato: md.tradovateapi.com serve quotazioni, DOM e grafici, non operazioni sugli ordini, quindi anche un host md non instraderà una chiamata di liquidazione.

Vale la pena segnalare una sottigliezza: mescolare gli ambienti, un token demo contro l'host live, o viceversa, si manifesta più spesso come un 401 che come un 404, ma vale comunque la pena controllarlo una volta che il percorso è pulito. I nomi host vengono aggiornati di tanto in tanto, quindi confermi quelli attuali nella documentazione ufficiale per sviluppatori di Tradovate, invece di fidarsi di un URL copiato da un vecchio gist.

Causa 3: ha inviato il metodo HTTP sbagliato

L'operazione di liquidazione è solo POST. Se invia un GET, il server non ha alcun gestore GET per quel percorso, il che si manifesta come un errore di tipo non trovato o metodo non consentito, a seconda di come lo segnala il suo client. È facile caderci se sta testando incollando l'URL nella barra degli indirizzi del browser: quello è sempre un GET, quindi qui fallirà sempre.

Effettui un test con un vero POST da un client adeguato. Ha anche bisogno delle intestazioni corrette nella richiesta: Content-Type: application/json e Authorization: Bearer <yourAccessToken>. Un POST con il corpo nel posto sbagliato, o senza il content type JSON, può fallire in modi che sembrano un problema di routing anche quando il percorso è corretto.

Causa 4: singolare o plurale, qual è quello reale?

È qui che nasce buona parte della confusione del tipo “l'endpoint non esiste”. L'operazione canonica, per singola posizione, è la route al singolare /order/liquidatePosition. Accetta un accountId e un singolo contractId e chiude quell'unica posizione netta. È questa la route che troverà documentata, ed è quella che risponde in modo costante.

Alcune librerie client e frammenti di codice della community fanno riferimento a una variante plurale in stile batch che accetta un array positions invece di un singolo contratto. Se copia un esempio al plurale ma la sua destinazione espone solo la route al singolare, oppure presume che il singolare accetti un array, otterrà un 404 oppure invierà un corpo che l'endpoint ignorerà. In caso di dubbio, utilizzi per impostazione predefinita il singolare /order/liquidatePosition con accountId e contractId, e verifichi il nome esatto dell'operazione e la sua struttura rispetto al riferimento API live per la versione che sta chiamando. L'ortografia e la scelta tra singolare e plurale sono esattamente i due dettagli che producono silenziosamente un 404.

La chiamata corretta, campo per campo

Una volta che la riga della richiesta è corretta, il corpo è breve.

POST https://demo.tradovateapi.com/v1/order/liquidatePosition
{ "accountId": 12345, "contractId": 67890, "admin": false, "customTag50": "" }

I due id sono il punto in cui la maggior parte delle persone si blocca, quindi proceda con attenzione. Chiami /account/list e legga l'id dall'oggetto account con cui vuole operare. Chiami /position/list, e ogni posizione aperta le restituisce sia un accountId sia un contractId, insieme alla sua quantità netta. Copi esattamente questi numeri, l'endpoint lavora sulla coppia (accountId, contractId), non su un id di posizione o su una stringa simbolo.

L'insidia dell'admin: un 401 nascosto dietro la sua soluzione

Questa insidia scatta proprio nel momento in cui si risolve il 404. Il campo admin è obbligatorio nel corpo, ma il valore che gli assegna è determinante. Impostando admin: true quando il suo utente API non è predisposto per l'accesso admin, la chiamata passa direttamente a 401 Unauthorized. Impostando admin: false la stessa richiesta va a buon fine. Quindi, a meno che non sappia che il suo utente ha privilegi admin, invii "admin": false. Se ha appena risolto un 404 e ora si trova davanti un 401 al tentativo immediatamente successivo, questa è quasi sempre la ragione, non il suo token, non l'id del suo account.

Cosa le offre l'endpoint, e cosa non offre

Vale la pena conoscere alcuni comportamenti prima di costruire qualcosa sopra questa chiamata:

• Chiude l'intera posizione netta per quella coppia (accountId, contractId). Dietro le quinte inserisce un ordine di chiusura, il che significa che non verrà eseguito quando il mercato è chiuso: lo esegua durante l'orario di negoziazione dello strumento.
• È una chiamata per contratto. Per chiudere tutto su un account, recuperi /position/list e cicli, lanciando una liquidatePosition per ogni contractId aperto. Su questa route non esiste un unico corpo “chiudi tutto l'account”.
• È sicuro rispetto alle race condition. Se la posizione si è già chiusa tra il suo controllo e la chiamata, ad esempio perché uno stop è stato eseguito, ottiene un 200 pulito con un corpo vuoto invece di un errore. È voluto, ed è più sicuro che sintetizzare un ordine sul lato opposto, che potrebbe aprire accidentalmente una posizione inversa.
• Non restituisce alcun orderId. Poiché nella risposta non è presente un id ordine, non può leggere direttamente il prezzo di esecuzione di chiusura. Se le serve quel prezzo per il P&L, effettui una riconciliazione con i report di esecuzione e fill (execution reports, fill pairs) o con il registro delle posizioni.

Una checklist rapida per risolvere il 404

Dove si inserisce PickMyTrade

La maggior parte delle persone alle prese con questo 404 non vuole davvero diventare idraulici dell'API Tradovate, vuole una strategia che apra, gestisca e chiuda le posizioni senza dover sorvegliare costantemente endpoint, id e token. PickMyTrade instrada gli alert di TradingView verso Tradovate e può chiudere o liquidare le posizioni come parte di una strategia, così non deve costruire a mano le chiamate di liquidazione, inseguire gli id di account e contratto, né gestire i token.

• Nessuna chiamata di liquidazione costruita a mano la sua strategia apre e chiude posizioni su Tradovate senza una sola richiesta API scritta a mano.
• Risoluzione di account e contratto gestita gli id che mandano in crisi le chiamate dirette vengono risolti al suo posto.
• Autenticazione gestita token e host vengono gestiti automaticamente, così un 401 nascosto dietro un 404 non diventa mai un suo problema.
• Routing sicuro rispetto ai rate limit distribuisce il flusso di ordini in modo che nulla rimbalzi contro i limiti di richiesta di Tradovate.