Error Codes

This document provides a comprehensive reference for all error codes returned by the Girard AI API.

Response Format

All API responses follow a consistent format:

Success Response

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": { ... },
    "hint": "Suggestion for fixing the error"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Authentication Errors (401)

These errors indicate problems with API authentication.

Example

# Missing API key
curl https://api.girardai.com/v1/workflows

# Response
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required",
    "hint": "Add Authorization header with format: Bearer gai_sk_..."
  }
}

Authorization Errors (403)

These errors indicate the API key is valid but lacks permission for the requested action.

Example

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "API key does not have permission to execute workflows",
    "details": {
      "required": ["workflow:execute"],
      "granted": ["workflow:read"]
    }
  }
}

Resource Errors (404)

These errors indicate the requested resource doesn't exist.

Example

{
  "success": false,
  "error": {
    "code": "WORKFLOW_NOT_FOUND",
    "message": "Workflow not found",
    "details": {
      "workflowId": "wf_abc123"
    }
  }
}

Validation Errors (400/422)

These errors indicate problems with the request data.

Validation Error Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "path": "steps[0].config.prompt",
        "message": "Required field is missing"
      },
      {
        "path": "name",
        "message": "String must contain at least 1 character(s)"
      }
    ]
  }
}

Rate Limiting Errors (429)

Rate Limit Headers

When rate limited, check these response headers:

Example

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "details": {
      "limit": 100,
      "remaining": 0,
      "resetAt": "2026-01-22T12:00:00Z",
      "retryAfter": 45
    }
  }
}

Server Errors (5xx)

These errors indicate server-side issues.

Example

{
  "success": false,
  "error": {
    "code": "AI_PROVIDER_ERROR",
    "message": "AI provider returned an error",
    "details": {
      "provider": "anthropic",
      "originalError": "Rate limit exceeded"
    }
  }
}

Error Handling Best Practices

1. Always Check success Field

const response = await fetch('/api/v1/workflows', {
  headers: { Authorization: `Bearer ${apiKey}` }
});

const data = await response.json();

if (!data.success) {
  console.error(`Error ${data.error.code}: ${data.error.message}`);
  // Handle error based on code
  return;
}

// Use data.data safely
console.log(data.data);

2. Implement Retry Logic for Transient Errors

async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);
    const data = await response.json();

    if (data.success) return data;

    // Retry on transient errors
    const retryableCodes = ['RATE_LIMITED', 'SERVICE_UNAVAILABLE', 'TIMEOUT'];
    if (retryableCodes.includes(data.error.code)) {
      const retryAfter = data.error.details?.retryAfter || Math.pow(2, attempt);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    // Don't retry on permanent errors
    throw new Error(data.error.message);
  }

  throw new Error('Max retries exceeded');
}

3. Handle Specific Error Codes

switch (data.error.code) {
  case 'MISSING_API_KEY':
  case 'INVALID_API_KEY':
    // Redirect to API key setup
    break;

  case 'RATE_LIMIT_EXCEEDED':
    // Show rate limit message, implement backoff
    break;

  case 'VALIDATION_ERROR':
    // Show field-level errors to user
    const fieldErrors = data.error.details;
    break;

  case 'WORKFLOW_NOT_FOUND':
    // Resource doesn't exist
    break;

  default:
    // Generic error handling
    break;
}

4. Log Request IDs for Support

Always log the requestId from the meta field when encountering errors:

if (!data.success) {
  console.error(`Error ${data.error.code} (Request ID: ${data.meta?.requestId})`);
  // Include requestId when contacting support
}

SDK Error Handling

Node.js SDK

import { Girard AI, GirardAIError } from '@girardai/sdk';

const client = new Girard AI({ apiKey: 'gai_sk_...' });

try {
  const workflow = await client.workflows.execute('wf_123', { input: {} });
} catch (error) {
  if (error instanceof GirardAIError) {
    console.log('Code:', error.code);
    console.log('Message:', error.message);
    console.log('Request ID:', error.requestId);

    if (error.code === 'RATE_LIMIT_EXCEEDED') {
      // Handle rate limiting
    }
  }
}

Python SDK

from girardai import Girard AI, GirardAIError

client = Girard AI(api_key="gai_sk_...")

try:
    workflow = client.workflows.execute("wf_123", input={})
except GirardAIError as e:
    print(f"Code: {e.code}")
    print(f"Message: {e.message}")
    print(f"Request ID: {e.request_id}")

    if e.code == "RATE_LIMIT_EXCEEDED":
        # Handle rate limiting
        pass

Status Codes Summary

Support

If you encounter persistent errors:

1. Check the Status Page for known issues
2. Include the requestId when contacting support
3. Email: api-support@girardai.com
4. Documentation: API Reference