Error Handling

Learn how to handle API errors gracefully in your application.

Error Response Format

All API errors follow a consistent JSON format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "path": "url",
        "message": "URL must start with http:// or https://"
      }
    ]
  },
  "requestId": "req_xxxxxxxxxxxxx"
}

The requestId is useful when contacting support about specific errors.

HTTP Status Codes

Error Codes

The error.code field contains a machine-readable error code:

Retry Strategy

For transient errors (5xx, 429), implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  let lastError;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        // Rate limited - get retry-after header
        const retryAfter = response.headers.get('Retry-After');
        const waitTime = retryAfter
          ? parseInt(retryAfter) * 1000
          : Math.pow(2, attempt) * 1000;

        await new Promise(r => setTimeout(r, waitTime));
        continue;
      }

      if (response.status >= 500) {
        // Server error - retry with backoff
        await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
        continue;
      }

      return response;
    } catch (error) {
      lastError = error;
      await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
    }
  }

  throw lastError;
}

Example Error Handling

async function createLink(url, slug) {
  const response = await fetch(
    'https://api.sniplink.co/v1/workspaces/{workspaceId}/links',
    {
      method: 'POST',
      headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ url, slug }),
    }
  );

  const data = await response.json();

  // Check for error response
  if (data.error) {
    switch (data.error.code) {
      case 'VALIDATION_ERROR':
        console.error('Invalid input:', data.error.details);
        break;
      case 'CONFLICT':
        console.error('Slug already taken, try a different one');
        break;
      case 'RATE_LIMIT_EXCEEDED':
        console.error('Too many requests, slow down');
        break;
      case 'UNAUTHORIZED':
        console.error('Check your API key');
        break;
      default:
        console.error('Error:', data.error.message);
    }
    // Include requestId for support
    if (data.requestId) {
      console.error('Request ID:', data.requestId);
    }
    return null;
  }

  return data.link;
}