Errors And Rate Limits

SDK Errors

The SDK throws VoyageApiError.

import { VoyageApiError } from "@voyage/sdk";

try {
  await voyage.journeys.publish("journey_123");
} catch (error) {
  if (error instanceof VoyageApiError) {
    console.error(error.status, error.code, error.message, error.requestId);
  }
}

Fields:

Field	Notes
`status`	HTTP status, or `0` for network/timeout failures
`code`	Worker or edge error code
`message`	Human-readable error
`details`	Validation details when provided
`requestId`	Edge or worker request ID when provided
`retryAfterMs`	Parsed `Retry-After` header when present

Retry Policy

The SDK retries idempotent methods (GET, HEAD, OPTIONS) twice by default for:

408, 429, 500, 502, 503, 504

Mutations are not retried by default. Enable retryMutations: true only when the caller has its own idempotency strategy.

Gateway Limits

Limit	Current value
API-key authentication attempts	60 per 60 seconds by key prefix
Default route profile	100 per 60 seconds
Downstream API-client dimension	tenant + API client ID + key prefix

Responses include:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1780627200

Auth Failures

Invalid, expired, revoked, disabled-client, disabled-tenant, malformed, and empty-scope keys return a generic 401 from the edge gateway:

{
  "error": {
    "code": "AUTH_INVALID",
    "message": "The provided authentication token is invalid",
    "requestId": "req_..."
  }
}

Do not branch on key-state details in client code; rotate or mint a fresh key through identity admin workflows.