Error Handling

Advanced

The Simplist SDK provides robust error handling with automatic retries, detailed error information, and timeout management.

All API errors are thrown as SimplistApiError instances with detailed information:

error-structure.ts

class SimplistApiError extends Error {
  statusCode: number     // HTTP status code
  error: string          // Error type
  details?: any          // Additional error details
  message: string        // Human-readable error message
}

Wrap SDK calls in try-catch blocks:

basic-error-handling.ts

import { SimplistClient, SimplistApiError } from "@simplist.blog/sdk"

// Uses SIMPLIST_API_KEY from environment variables
const client = new SimplistClient()

try {
  const response = await client.articles.get('article-slug')
  console.log(response.data)
} catch (error) {
  if (error instanceof SimplistApiError) {
    console.error(`API Error [${error.statusCode}]: ${error.message}`)
    console.error('Error type:', error.error)
    console.error('Details:', error.details)
  } else {
    console.error('Unexpected error:', error)
  }
}

Status	Error	Solution
400	Bad Request	Check request parameters
401	Unauthorized	Verify your API key
403	Forbidden	Check API key permissions
404	Not Found	Verify the slug or ID
429	Too Many Requests	Wait before retrying
500	Internal Server Error	Retry with backoff
503	Service Unavailable	Retry later

handle-by-status.ts

import { SimplistClient, SimplistApiError } from "@simplist.blog/sdk"

// Uses SIMPLIST_API_KEY from environment variables
const client = new SimplistClient()

async function getArticle(slug: string) {
  try {
    const response = await client.articles.get(slug)
    return response.data
  } catch (error) {
    if (error instanceof SimplistApiError) {
      switch (error.statusCode) {
        case 404:
          console.error('Article not found')
          return null

        case 401:
          console.error('Authentication failed - check your API key')
          throw error

        case 429:
          console.error('Rate limit exceeded - waiting before retry')
          await new Promise(resolve => setTimeout(resolve, 5000))
          return getArticle(slug) // Retry after delay

        case 500:
        case 503:
          console.error('Server error - will retry automatically')
          throw error

        default:
          console.error(`Unexpected error: ${error.message}`)
          throw error
      }
    }

    throw error
  }
}

The SDK automatically retries failed requests with exponential backoff.

Property	Type	Description	Default
`retries`	number	Number of retry attempts	3
`retryDelay`	number	Initial delay (ms)	1000
`timeout`	number	Request timeout (ms)	10000

Retries on: Network errors, timeouts, 5xx server errors
No retries on: 4xx client errors (bad request, auth, not found)
Backoff: Exponential (1s, 2s, 4s, 8s...)

custom-retries.ts

import { SimplistClient } from "@simplist.blog/sdk"

const client = new SimplistClient({
  apiKey: process.env.SIMPLIST_API_KEY,
  retries: 5,           // Retry up to 5 times
  retryDelay: 2000,     // Start with 2 second delay
  timeout: 15000        // 15 second timeout
})

// Retries: 2s, 4s, 8s, 16s, 32s

no-retries.ts

const client = new SimplistClient({
  apiKey: process.env.SIMPLIST_API_KEY,
  retries: 0  // No retries
})

Requests that exceed the timeout are automatically cancelled:

timeout-handling.ts

import { SimplistClient } from "@simplist.blog/sdk"

const client = new SimplistClient({
  apiKey: process.env.SIMPLIST_API_KEY,
  timeout: 5000  // 5 second timeout
})

try {
  const response = await client.articles.get('article-slug')
} catch (error) {
  if (error.name === 'AbortError') {
    console.error('Request timed out after 5 seconds')
  }
}

The SDK validates configuration on initialization:

missing-api-key.ts

try {
  const client = new SimplistClient()  // No API key provided
} catch (error) {
  // Error: API key is required. Provide it via options.apiKey
  // or set SIMPLIST_API_KEY environment variable.
}

invalid-api-key.ts

try {
  const client = new SimplistClient({
    apiKey: 'invalid-key'
  })
} catch (error) {
  // Error: Invalid API key format. API key should contain
  // an underscore (e.g., "prj_your_api_key_here")
}

Handle network connectivity issues:

network-errors.ts

import { SimplistClient, SimplistApiError } from "@simplist.blog/sdk"

// Uses SIMPLIST_API_KEY from environment variables
const client = new SimplistClient()

async function fetchWithNetworkHandling(slug: string) {
  try {
    const response = await client.articles.get(slug)
    return response.data
  } catch (error) {
    if (error instanceof TypeError && error.message.includes('fetch')) {
      console.error('Network error - check internet connection')
      return null
    }

    if (error instanceof SimplistApiError) {
      console.error(`API error: ${error.message}`)
      return null
    }

    console.error('Unknown error:', error)
    return null
  }
}

Provide fallback content when API calls fail:

graceful-degradation.tsx

import { SimplistClient, SimplistApiError } from "@simplist.blog/sdk"
import { Suspense } from "react"

// Uses SIMPLIST_API_KEY from environment variables
const client = new SimplistClient()

export default async function ArticleList() {
  try {
    const response = await client.articles.latest(10)
    const articles = response.data

    return (
      <div>
        {articles.map(article => (
          <article key={article.id}>
            <h2>{article.title}</h2>
            <p>{article.excerpt}</p>
          </article>
        ))}
      </div>
    )
  } catch (error) {
    if (error instanceof SimplistApiError) {
      // Log error for monitoring
      console.error('Failed to fetch articles:', error)

      // Show fallback UI
      return (
        <div className="error">
          <h2>Unable to load articles</h2>
          <p>Please try again later.</p>
        </div>
      )
    }

    throw error
  }
}

Integrate with error tracking services:

error-monitoring.ts

import { SimplistClient, SimplistApiError } from "@simplist.blog/sdk"
import * as Sentry from "@sentry/nextjs"

// Uses SIMPLIST_API_KEY from environment variables
const client = new SimplistClient()

async function fetchArticleWithMonitoring(slug: string) {
  try {
    const response = await client.articles.get(slug)
    return response.data
  } catch (error) {
    // Log to error tracking service
    if (error instanceof SimplistApiError) {
      Sentry.captureException(error, {
        contexts: {
          api: {
            endpoint: 'articles.get',
            slug,
            statusCode: error.statusCode
          }
        }
      })
    } else {
      Sentry.captureException(error)
    }

    throw error
  }
}

Use the ping() method to test connectivity:

ping.ts

import { SimplistClient, SimplistApiError } from "@simplist.blog/sdk"

// Uses SIMPLIST_API_KEY from environment variables
const client = new SimplistClient()

async function testConnection() {
  try {
    const response = await client.ping()
    console.log('API connection successful')
    console.log('Status:', response.status)
    console.log('Timestamp:', response.timestamp)
    return true
  } catch (error) {
    if (error instanceof SimplistApiError) {
      console.error(`Connection failed: ${error.message}`)
    }
    return false
  }
}

// Check before making other requests
if (await testConnection()) {
  // Proceed with API calls
}

Here's a production-ready example with comprehensive error handling:

production-example.ts

import { SimplistClient, SimplistApiError } from "@simplist.blog/sdk"
import * as Sentry from "@sentry/nextjs"

const client = new SimplistClient({
  apiKey: process.env.SIMPLIST_API_KEY,
  retries: 3,
  retryDelay: 1000,
  timeout: 10000
})

export async function getArticle(slug: string) {
  try {
    const response = await client.articles.get(slug)
    return {
      data: response.data,
      error: null
    }
  } catch (error) {
    // Handle SimplistApiError
    if (error instanceof SimplistApiError) {
      Sentry.captureException(error, {
        contexts: {
          api: {
            endpoint: 'articles.get',
            slug,
            statusCode: error.statusCode,
            errorType: error.error
          }
        }
      })

      return {
        data: null,
        error: {
          message: error.message,
          statusCode: error.statusCode,
          type: error.error
        }
      }
    }

    // Handle network errors
    if (error instanceof TypeError && error.message.includes('fetch')) {
      Sentry.captureMessage('Network error fetching article', {
        level: 'warning',
        extra: { slug }
      })

      return {
        data: null,
        error: {
          message: 'Network error - please check your connection',
          statusCode: 0,
          type: 'NetworkError'
        }
      }
    }

    // Handle unknown errors
    Sentry.captureException(error)

    return {
      data: null,
      error: {
        message: 'An unexpected error occurred',
        statusCode: 0,
        type: 'UnknownError'
      }
    }
  }
}

// Usage in Next.js
export default async function ArticlePage({ params }: {
  params: { slug: string }
}) {
  const { data: article, error } = await getArticle(params.slug)

  if (error) {
    if (error.statusCode === 404) {
      return <div>Article not found</div>
    }

    return (
      <div>
        <h1>Error loading article</h1>
        <p>{error.message}</p>
      </div>
    )
  }

  return (
    <article>
      <h1>{article.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: article.content }} />
    </article>
  )
}

Wrap all SDK calls in try-catch blocks to handle potential errors.

Use instanceof SimplistApiError to distinguish API errors from network errors.

Return null or show "not found" UI instead of crashing.

Send errors to monitoring services for debugging and alerting.

Show user-friendly error messages and fallback UI.

Let the SDK handle automatic retries for transient errors.

Test how your app behaves when API calls fail.

Complete Examples

Production-ready integration examples

Articles API

Learn about the Articles API

Quick Help

Yes, wrap all SDK calls in try-catch blocks. The SDK throws SimplistApiError for API errors and standard errors for network issues. Always handle both types for robust error handling.

The SDK automatically retries failed requests with exponential backoff (default: 3 retries starting at 1s delay). It only retries on network errors, timeouts, and 5xx server errors. 4xx client errors are not retried.

For 404 errors, return null or a fallback value instead of throwing. This allows your app to gracefully handle missing content without crashing. Use notFound() in Next.js for proper 404 pages.

Edit on GitHub

Multilingual Blog

Overview

Error Types

SimplistApiError

Basic Error Handling

HTTP Status Codes

Common Status Codes

Error Handling by Status

Automatic Retries

Default Retry Configuration

Retry Behavior

Custom Retry Configuration

Disable Retries

Timeout Handling

Validation Errors

Missing API Key

Invalid API Key Format

Network Errors

Graceful Degradation

Error Monitoring

Testing API Connection

Complete Error Handling Example

Best Practices

1. Always Use Try-Catch

2. Check Error Type

3. Handle 404s Gracefully

4. Log Errors

5. Provide Fallbacks

6. Retry Strategically

7. Test Error Paths

Next Steps

Complete Examples

Articles API

Frequently Asked Questions

Quick Help

Command Palette