Error Reference

{
  error: string;     // human-readable message
  code?: string;     // machine-readable code (present on errors that benefit from programmatic handling)
  retryable?: boolean; // true if retrying the exact same request may succeed
  // Additional context fields may appear for specific errors:
  upgrade_url?: string;
}

{
  "error": "BYOAK requires a Pro subscription",
  "code": "BYOAK_REQUIRES_PRO",
  "upgrade_url": "/settings/billing"
}

{ "error": "Bearer token required" }

{ "error": "Invalid API key format" }

{ "error": "Project is suspended" }

{ "error": "Free plan is limited to 3 projects" }

{
  "error": "BYOAK requires a Pro subscription",
  "code": "BYOAK_REQUIRES_PRO",
  "upgrade_url": "/settings/billing"
}

{ "error": "Maximum of 3 tiers per project" }

{
  "error": "No deployed settings to revert to. Deploy at least once before discarding draft.",
  "code": "NO_DEPLOYED_SNAPSHOT"
}

{ "error": "No draft to publish", "code": "NO_DRAFT" }

{
  "error": "provider key validation failed — the key was rejected by the provider API",
  "code": "KEY_VALIDATION_FAILED"
}

{
  "error": "Your tenant has not configured a OpenAI API key.",
  "code": "PROVIDER_NOT_CONFIGURED"
}

{
  "error": "rate limit exceeded",
  "message": "API rate limit exceeded"
}

{
  "error": "Too many validation requests. Try again in a minute.",
  "code": "RATE_LIMITED"
}

{ "error": "Playground rate limit exceeded (50/hour)" }

{
  "error": "Settings saved but failed to sync to gateway. Please retry deploy.",
  "code": "REDIS_SYNC_FAILED",
  "retryable": true
}

async function mintTokenSafe(
  apiKey: string,
  userId: string
): Promise<string | null> {
  const resp = await fetch("https://api.behest.app/auth/v1/auth/mint", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${apiKey}`,
    },
    body: JSON.stringify({ user_id: userId }),
  });
 
  if (resp.ok) {
    const { access_token } = await resp.json();
    return access_token;
  }
 
  const body = await resp.json().catch(() => ({ error: "unknown" }));
 
  switch (resp.status) {
    case 400:
      // Validation error — log and fix the request
      console.error("Mint validation error:", body.error);
      return null;
 
    case 401:
      // Auth error — check key, check project status
      if (body.error === "Project is suspended") {
        throw new Error("Project suspended — contact Behest support");
      }
      throw new Error(`Authentication failed: ${body.error}`);
 
    case 429: {
      // Rate limited — respect Retry-After
      const retryAfter = parseInt(resp.headers.get("Retry-After") ?? "60", 10);
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      return mintTokenSafe(apiKey, userId); // retry once
    }
 
    case 500:
    case 502:
      if (body.retryable) {
        // Transient error — retry with backoff
        await new Promise((r) => setTimeout(r, 2000));
        return mintTokenSafe(apiKey, userId);
      }
      throw new Error(`Server error: ${body.error}`);
 
    default:
      throw new Error(`Unexpected status ${resp.status}: ${body.error}`);
  }
}

{
  "error": "...",
  "message": "..."
}