Chyby a opakování požadavků (CZ)

Obálka chyby

Každá chybová REST odpověď z Voke má stejný JSON tvar:

{
  "statusCode": 400,
  "message": "Human-readable description",
  "error": "Bad Request",
  "code": "VALIDATION_ERROR",
  "details": ["field: message"]
}

Pole code je stabilní kontrakt — jde o řetězec z enumu ApiErrorCode, který se mezi minor verzemi nezmění. message a details jsou informativní a mohou se změnit. Logiku zpracování chyb stavte na code, nikoli na message.

Úplný seznam všech kódů a jejich mapování na HTTP stavy najdete v Reference / Error Codes.

REST chyby, na které partneři narazí

Toto jsou hodnoty ApiErrorCode, na které partner pravděpodobně narazí při volání REST API Voke (správa API klíčů, trading konfigurace, endpointy org-contextu).

Kódy odmítnutí VCP příkazů

Když Voke odmítne příkaz, AMQP ack zpráva (event.command.ack) má status: "REJECTED" a rejectionCode z enumu RejectionCode.

Selhání AMQP autentizace

Selhání AMQP autentizace a autorizace nejsou HTTP chyby — nastávají na úrovni RabbitMQ protokolu při navazování spojení nebo otevírání kanálu. Voke používá rabbitmq_auth_backend_http k validaci přihlašovacích údajů na straně serveru.

Tato selhání jsou na straně Voke logována v AmqpAuthController. Partneři vidí pouze odmítnutí na úrovni protokolu. Pokud spojení, které dříve fungovalo, najednou začne selhávat, nejpravděpodobnější příčinou je rotace nebo zneplatnění API klíče — vytvořte nový klíč se scope vcp:connect a aktualizujte svého konzumenta.

Doporučení k opakování

REST

VCP (AMQP zprávy)

Výpadky AMQP spojení

Připojte se znovu okamžitě (bez čekání při prvním pokusu), poté při dalších selháních aplikujte backoff. Fronty jsou durable a zprávy jsou persistent — během vašeho odpojení se nic neztratí. Nepotvrzené (unacked) zprávy se po opětovném připojení automaticky znovu doručí.

Idempotence

• Vždy nastavte unikátní messageId v každé VCP obálce, kterou odesíláte. Použijte UUID v4 nebo identifikátor odolný proti kolizím. messageId je vaše hlavní vodítko pro korelaci acků a statusů.
• Voke deduplikuje příchozí příkazy podle messageId po dobu 10 minut přes Redis (vcp:seen:{orgSlug}:{messageId}, atomické SET NX EX 600). První doručení proběhne; duplikáty uvnitř okna jsou potvrzeny na brokeru a tiše zahozeny — na replay se partnerovi nepublikuje zpět žádný ACK, takže na něj nečekejte. Pokud downstream zpracování vyhodí výjimku, Voke uvolní claim, takže legitimní opakování se stejným messageId proběhne. Mimo 10minutové okno bude stejné messageId zpracováno znovu — navrhujte příkazy tak, aby byly sémanticky idempotentní (scheduleId, correlationId, stabilní reference příkazů), místo spoléhání pouze na replay guard. Úplný kontrakt replay guardu viz VCP message integrity.
• Partneři musí deduplikovat příchozí události podle messageId lokálně. Po reconnectu konzumenta může RabbitMQ znovu doručit poslední nepotvrzený batch. Pro většinu případů postačí jednoduchá in-memory LRU množina posledních N hodnot messageId.

Observabilita

Partneři typicky logují každý příchozí ack a status event klíčovaný podle correlationId, aby šel kompletní round-trip příkazu rekonstruovat jen z partnerských logů:

[correlationId: req-abc123] SEND  command.site-setpoint  messageId: msg-001
[correlationId: req-abc123] ACK   QUEUED                 messageId: msg-001-ack
[correlationId: req-abc123] STATUS EXECUTING             messageId: msg-001-status-1
[correlationId: req-abc123] STATUS COMPLETED             messageId: msg-001-status-2

Na straně Voke VcpCommandLog uchovává stejnou timeline — každý příkaz, ack a status event je řádek klíčovaný podle messageId a correlationId. Při zakládání incidentu uveďte messageId a Voke ops během sekund najde odpovídající řádky VcpCommandLog.

Související odkazy

• Reference / Error Codes — úplná tabulka ApiErrorCode s HTTP stavem a popisy
• Commands — typy příkazů, routing keys, ack flow
• VCP message integrity — struktura obálky a podpis