Error handling - Help Genie

When a request fails, the API returns a JSON response with success: false and an error object containing a machine-readable code, a human-readable message, and the HTTP status code.

Error response format

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404
  }
}

boolean

Always false for error responses.

object

string

A machine-readable error code. Use this for programmatic error handling.

string

A human-readable description of the error. Suitable for logging but not guaranteed to be stable across versions.

number

The HTTP status code associated with the error.

Error codes

Code	HTTP status	Description
`UNAUTHORIZED`	401	No authentication header provided. Include `Authorization: Bearer hg_live_YOUR_KEY` or `X-API-Key: hg_live_YOUR_KEY`.
`INVALID_KEY_PREFIX`	401	API key format is invalid. Keys must start with `hg_live_` or `hg_admin_`.
`KEY_NOT_FOUND`	401	API key not found or has been revoked. Generate a new key at Settings → API Keys.
`INVALID_TOKEN`	401	Session token is malformed, expired, or has been revoked. Refresh the session and retry.
`FORBIDDEN`	403	The authenticated user does not have permission to access this resource or perform this action.
`NOT_FOUND`	404	The requested resource does not exist or the user does not have access to it.
`VALIDATION_ERROR`	400	The request body is missing required fields, contains invalid data, or has malformed JSON.
`AGENT_NOT_FOUND`	404	The specified genie (agent) does not exist or the user does not have access to it.
`INVALID_ACTION`	400	The `action` value is not supported for the specified resource.
`RATE_LIMIT_EXCEEDED`	429	Too many requests. API keys are limited to 60 requests/minute. Wait before retrying.
`INTERNAL_ERROR`	500	An unexpected server error occurred. If this persists, contact support.

Handling errors in code

With ApiService

ApiService.invoke() throws on error. Wrap calls in try/catch:

import { ApiService } from "@/services/api/ApiService";

try {
  const genie = await ApiService.invoke({
    resource: "genies",
    action: "get",
    id: "abc-123",
  });
} catch (error) {
  console.error("API request failed:", error.message);
}

With fetch

When using fetch directly, check the success field in the response body:

const response = await fetch(
  "https://api.helpgenie.ai/v1",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer hg_live_YOUR_KEY`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      resource: "genies",
      action: "get",
      id: "abc-123",
    }),
  }
);

const result = await response.json();

if (!result.success) {
  const { code, message, status } = result.error;

  switch (code) {
    case "UNAUTHORIZED":
    case "INVALID_TOKEN":
      // Refresh the auth session and retry
      break;
    case "NOT_FOUND":
    case "AGENT_NOT_FOUND":
      // Resource does not exist or is not accessible
      break;
    case "VALIDATION_ERROR":
      // Fix the request body and retry
      break;
    case "RATE_LIMIT_EXCEEDED":
      // Wait and retry with exponential backoff
      break;
    default:
      console.error(`API error [${code}]: ${message}`);
  }
}

With TanStack Query

When using TanStack Query (React Query), errors propagate through the query’s error state:

import { useQuery } from "@tanstack/react-query";
import { ApiService } from "@/services/api/ApiService";

const { data, error, isError } = useQuery({
  queryKey: ["genies"],
  queryFn: () =>
    ApiService.invoke({
      resource: "genies",
      action: "all",
    }),
});

if (isError) {
  console.error("Failed to load genies:", error.message);
}

Retry strategy

Use exponential backoff for 429 and 500 errors. These are the only error codes worth retrying automatically. Authentication errors (401) require a token refresh, and validation errors (400, 403, 404) indicate a problem with the request itself.A recommended approach:

Start with a 1-second delay after the first failure.
Double the delay after each subsequent failure (1s, 2s, 4s, 8s…).
Add random jitter (0-500ms) to avoid thundering herd problems.
Give up after 3-4 retries and surface the error to the user.

const delay = (ms: number) =>
  new Promise((resolve) => setTimeout(resolve, ms));

async function fetchWithRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      const code = error?.code ?? error?.error?.code;
      const isRetryable =
        code === "RATE_LIMIT_EXCEEDED" || code === "INTERNAL_ERROR";

      if (!isRetryable || attempt === maxRetries) {
        throw error;
      }

      const backoff = 1000 * Math.pow(2, attempt);
      const jitter = Math.random() * 500;
      await delay(backoff + jitter);
    }
  }
  throw new Error("Max retries exceeded");
}

// Usage
const genies = await fetchWithRetry(() =>
  ApiService.invoke({ resource: "genies", action: "all" })
);

#!/bin/bash
# Retry with exponential backoff for 429 and 500 errors

URL="https://api.helpgenie.ai/v1"
TOKEN="hg_live_YOUR_KEY"
MAX_RETRIES=3

for attempt in $(seq 0 $MAX_RETRIES); do
  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$URL" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"resource": "genies", "action": "all"}')

  HTTP_CODE=$(echo "$RESPONSE" | tail -1)
  BODY=$(echo "$RESPONSE" | sed '$d')

  if [ "$HTTP_CODE" -ne 429 ] && [ "$HTTP_CODE" -ne 500 ]; then
    echo "$BODY"
    exit 0
  fi

  if [ "$attempt" -eq "$MAX_RETRIES" ]; then
    echo "Max retries exceeded. Last response: $BODY" >&2
    exit 1
  fi

  DELAY=$(( (1 << attempt) ))
  echo "Retrying in ${DELAY}s (attempt $((attempt + 1))/$MAX_RETRIES)..." >&2
  sleep "$DELAY"
done

Common error scenarios

401 — Missing or expired token

The most common cause is an expired access token. Supabase tokens typically expire after 1 hour. Use supabase.auth.refreshSession() to get a new token.

const { data, error } = await supabase.auth.refreshSession();
const newToken = data.session?.access_token;

400 — Invalid action for resource

Each resource supports a specific set of actions. Sending an unsupported action (e.g., action: "archive" to a resource that does not support it) returns INVALID_ACTION. Check the resource’s documentation in the API reference for supported actions.

403 — Insufficient permissions

The user’s role does not allow the requested operation. For example, a consumer user cannot create genies. See Introduction for the role permission matrix.

404 — Resource not found

The record either does not exist or belongs to another user. Non-admin users can only access their own resources. Verify the id value and confirm the user has access.

429 — Rate limit exceeded

Back off and retry with exponential delay. A simple implementation:

const delay = (ms: number) =>
  new Promise((resolve) => setTimeout(resolve, ms));

async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      if (
        error?.code === "RATE_LIMIT_EXCEEDED" &&
        attempt < maxRetries - 1
      ) {
        await delay(1000 * Math.pow(2, attempt));
        continue;
      }
      throw error;
    }
  }
  throw new Error("Max retries exceeded");
}

​Error response format

​Error codes

​Handling errors in code

​With ApiService

​With fetch

​With TanStack Query

​Retry strategy

​Common error scenarios