Errors and Retries

Error envelope

Every Voke REST error response follows the same JSON shape:

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

The code field is the stable contract — it is an ApiErrorCode enum string that will not change between minor releases. message and details are informational and may change. Build error-handling logic against code, not message.

For the full list of all codes and their HTTP status mappings, see Reference / Error Codes.

REST errors partners will encounter

These are the ApiErrorCode values a partner is likely to encounter when calling Voke's REST API (API key management, trading config, org-context endpoints).

VCP command rejection codes

When Voke rejects a command, the AMQP ack message (event.command.ack) has status: "REJECTED" and a rejectionCode from the RejectionCode enum.

AMQP auth failures

AMQP authentication and authorization failures are not HTTP errors — they occur at the RabbitMQ protocol layer during connection or channel open. Voke uses rabbitmq_auth_backend_http to validate credentials server-side.

These failures are logged on the Voke side in the AmqpAuthController. Partners see only the protocol-level refusal. If a connection that previously worked suddenly starts failing, the most likely cause is an API key rotation or revocation — create a new key with vcp:connect scope and update your consumer.

Retry guidance

REST

VCP (AMQP messages)

AMQP connection drops

Reconnect immediately (no wait on first attempt), then apply backoff on subsequent failures. Queues are durable and messages are persistent — nothing is lost while you are disconnected. Unacked messages redeliver automatically when you reconnect.

Idempotency

• Always set a unique messageId in every VCP envelope you send. Use a UUID v4 or a collision-resistant identifier. The messageId is your primary handle for correlating acks and statuses.
• Voke deduplicates inbound commands by messageId for 10 minutes via Redis (vcp:seen:{orgSlug}:{messageId}, atomic SET NX EX 600). The first delivery proceeds; duplicates inside the window are acked at the broker and silently dropped — no ACK is published back to the partner for a replay, so do not wait on one. If downstream processing throws, Voke releases the claim so a legitimate retry with the same messageId proceeds. Outside the 10-minute window the same messageId will be reprocessed — design commands to be semantically idempotent (scheduleId, correlationId, stable command refs) rather than relying on the replay guard alone. See VCP message integrity for the full replay-guard contract.
• Partners must deduplicate inbound events by messageId locally. After a consumer reconnect, RabbitMQ may redeliver the most recently unacknowledged batch. A simple in-memory LRU set of the last N messageId values is sufficient for most cases.

Observability

Partners typically log every inbound ack and status event keyed by correlationId so the complete command round-trip is reconstructable from partner logs alone:

[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

On Voke's side, VcpCommandLog persists the same timeline — every command, ack, and status event is a row keyed by messageId and correlationId. When filing an incident, provide the messageId and Voke ops can find the corresponding VcpCommandLog rows within seconds.

Cross-links

• Reference / Error Codes — full ApiErrorCode table with HTTP status and descriptions
• Commands — command types, routing keys, ack flow
• VCP message integrity — envelope structure and signing