Error Handling

{
  "error": {
    "code": "validation_error",
    "message": "The email field is required",
    "details": {
      "field": "email",
      "reason": "required"
    }
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed for 2 fields",
    "details": {
      "errors": [
        {
          "field": "email",
          "code": "invalid_format",
          "message": "Must be a valid email address"
        },
        {
          "field": "phone",
          "code": "required_field",
          "message": "Phone number is required"
        }
      ]
    }
  }
}

{
  "error": {
    "code": "token_expired",
    "message": "Your access token has expired",
    "details": {
      "expired_at": "2024-01-15T10:30:00Z"
    }
  }
}

{
  "error": {
    "code": "insufficient_permissions",
    "message": "Your API key does not have permission to delete records",
    "details": {
      "required_permission": "delete",
      "current_permissions": ["read", "write"]
    }
  }
}

{
  "error": {
    "code": "record_not_found",
    "message": "Record not found",
    "details": {
      "module": "contacts",
      "record_id": "rec_abc123"
    }
  }
}

{
  "error": {
    "code": "uniqueness_violation",
    "message": "A record with this email already exists",
    "details": {
      "field": "email",
      "value": "[email protected]",
      "existing_record_id": "rec_xyz789"
    }
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds",
    "details": {
      "limit": 1000,
      "window": "1 minute",
      "retry_after": 60
    }
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again.",
    "details": {
      "request_id": "req_abc123xyz"
    }
  }
}

import { CoherenceClient, CoherenceError } from '@coherence/sdk';
 
const client = new CoherenceClient({ apiKey: 'YOUR_API_KEY' });
 
async function createContact(data: ContactData) {
  try {
    const contact = await client.modules.contacts.records.create(data);
    return contact;
  } catch (error) {
    if (error instanceof CoherenceError) {
      switch (error.code) {
        case 'validation_error':
          // Handle field validation errors
          console.error('Validation failed:', error.details.errors);
          break;
        case 'duplicate_record':
          // Handle duplicate - maybe update instead
          console.error('Record already exists:', error.details.existing_record_id);
          break;
        case 'rate_limit_exceeded':
          // Wait and retry
          const retryAfter = error.details.retry_after || 60;
          await sleep(retryAfter * 1000);
          return createContact(data);
        case 'token_expired':
          // Refresh token and retry
          await refreshToken();
          return createContact(data);
        default:
          console.error('API error:', error.message);
      }
    }
    throw error;
  }
}

from coherence import CoherenceClient, CoherenceError
import time
 
client = CoherenceClient(api_key="YOUR_API_KEY")
 
def create_contact(data):
    try:
        contact = client.modules.contacts.records.create(data)
        return contact
    except CoherenceError as error:
        if error.code == "validation_error":
            # Handle field validation errors
            print(f"Validation failed: {error.details['errors']}")
        elif error.code == "duplicate_record":
            # Handle duplicate - maybe update instead
            print(f"Record exists: {error.details['existing_record_id']}")
        elif error.code == "rate_limit_exceeded":
            # Wait and retry
            retry_after = error.details.get("retry_after", 60)
            time.sleep(retry_after)
            return create_contact(data)
        elif error.code == "token_expired":
            # Refresh token and retry
            refresh_token()
            return create_contact(data)
        else:
            print(f"API error: {error.message}")
        raise

response=$(curl -s -w "\n%{http_code}" -X POST \
  "https://api.getcoherence.io/v1/modules/contacts/records" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "John Smith"}')
 
# Extract status code (last line)
http_code=$(echo "$response" | tail -n1)
# Extract body (all but last line)
body=$(echo "$response" | sed '$d')
 
if [ "$http_code" -ge 400 ]; then
  echo "Error $http_code: $(echo $body | jq -r '.error.message')"
  exit 1
fi
 
echo "Success: $(echo $body | jq -r '.data.id')"

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries: number = 3,
  baseDelay: number = 1000
): Promise<T> {
  let lastError: Error;
 
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;
 
      // Check if error is retryable
      if (error instanceof CoherenceError) {
        const retryableCodes = [
          'internal_error',
          'service_unavailable',
          'timeout'
        ];
 
        if (!retryableCodes.includes(error.code)) {
          throw error; // Non-retryable, fail immediately
        }
 
        // For rate limits, use the provided retry time
        if (error.code === 'rate_limit_exceeded') {
          const retryAfter = error.details?.retry_after || 60;
          await sleep(retryAfter * 1000);
          continue;
        }
      }
 
      // Exponential backoff with jitter
      const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 1000;
      console.log(`Retry ${attempt + 1}/${maxRetries} after ${delay}ms`);
      await sleep(delay);
    }
  }
 
  throw lastError;
}
 
// Usage
const contact = await withRetry(() =>
  client.modules.contacts.records.create({ name: 'John' })
);

class CircuitBreaker {
  private failures = 0;
  private lastFailure: number = 0;
  private state: 'closed' | 'open' | 'half-open' = 'closed';
 
  constructor(
    private threshold: number = 5,
    private resetTimeout: number = 30000
  ) {}
 
  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'open') {
      if (Date.now() - this.lastFailure > this.resetTimeout) {
        this.state = 'half-open';
      } else {
        throw new Error('Circuit breaker is open');
      }
    }
 
    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }
 
  private onSuccess() {
    this.failures = 0;
    this.state = 'closed';
  }
 
  private onFailure() {
    this.failures++;
    this.lastFailure = Date.now();
    if (this.failures >= this.threshold) {
      this.state = 'open';
    }
  }
}

catch (error) {
  console.error('API Error:', {
    code: error.code,
    message: error.message,
    details: error.details,
    requestId: error.details?.request_id
  });
}

if (error.code === 'duplicate_record') {
  // Specific handling
} else if (error.status === 400) {
  // Generic client error handling
} else {
  // Fallback
}

const userMessages: Record<string, string> = {
  'validation_error': 'Please check your input and try again.',
  'rate_limit_exceeded': 'Too many requests. Please wait a moment.',
  'internal_error': 'Something went wrong. Please try again later.',
  'not_found': 'The requested item could not be found.',
};
 
const friendlyMessage = userMessages[error.code] || 'An error occurred.';