Skip to main content

​
Overview

The ReferralLoop API uses standard HTTP status codes to indicate success or failure. This guide explains common error codes and how to handle them.

​
Error Response Format

All error responses follow this format: 
{
  "error": "Error message describing what went wrong"
}
Some errors may include additional fields: 
{
  "error": "Email already exists on this waitlist",
  "signup": {
    "id": "...",
    "position": 1,
    "referral_code": "ABC123"
  }
}

​
HTTP Status Codes

​
400 Bad Request

The request was malformed or contained invalid parameters. Common causes:
  • Missing required fields
  • Invalid data types
  • Invalid parameter values
Example: 
{
  "error": "Email is required"
}

​
401 Unauthorized

The API key is missing, invalid, or expired. Common causes:
  • Missing Authorization header
  • Invalid API key format
  • Expired or revoked API key
Example: 
{
  "error": "Invalid API key"
}

​
403 Forbidden

The request is valid, but the action is not allowed. Common causes:
  • Free plan attempting to use API (API access requires paid plan)
  • Insufficient permissions
Example: 
{
  "error": "API access requires a paid subscription",
  "message": "Upgrade your plan to use the API",
  "upgrade_url": "https://www.referralloop.dev/dashboard/billing"
}

​
404 Not Found

The requested resource doesn’t exist. Common causes:
  • Invalid waitlist ID
  • Invalid signup ID
  • Resource was deleted
Example: 
{
  "error": "Waitlist not found"
}

​
409 Conflict

The request conflicts with the current state of the resource. Common causes:
  • Email already exists on waitlist
  • Duplicate resource creation
Example: 
{
  "error": "Email already exists on this waitlist",
  "signup": {
    "id": "789e0123-e89b-12d3-a456-426614174000",
    "position": 1,
    "referral_code": "ABC123"
  }
}

​
429 Too Many Requests

The rate limit has been exceeded. Example: 
{
  "error": "Rate limit exceeded",
  "limit": 1000,
  "reset_at": "2024-01-15T11:00:00Z"
}
See Rate Limits for more information.

​
500 Internal Server Error

An unexpected error occurred on the server. What to do:
  • Retry the request after a short delay
  • If the problem persists, contact support
Example: 
{
  "error": "Failed to fetch waitlists"
}

​
Error Handling Best Practices

  1. Always check the status code before processing the response
  2. Read the error message to understand what went wrong
  3. Implement retry logic for 5xx errors with exponential backoff
  4. Handle rate limits by checking the X-RateLimit-Remaining header
  5. Log errors for debugging and monitoring

​
Example Error Handling

try {
  const response = await fetch(
    "https://www.referralloop.dev/api/v1/waitlists",
    {
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
    }
  );

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 401:
        console.error("Invalid API key");
        break;
      case 429:
        console.error("Rate limit exceeded");
        const resetAt = response.headers.get("X-RateLimit-Reset");
        console.error(`Retry after: ${resetAt}`);
        break;
      default:
        console.error("API error:", error.error);
    }

    throw new Error(error.error);
  }

  const data = await response.json();
  return data;
} catch (error) {
  console.error("Request failed:", error);
  throw error;
}