HTTP Status Codes

Overview

The SiteAssist API uses standard HTTP status codes to indicate the success or failure of requests. Status codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.

Status Codes

Success Responses (2xx)

200 OK

Standard success response. The request was processed successfully and the response contains the requested data.

{
  "object": "conversation",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "open",
  "messages": []
}

201 Created

A new resource was successfully created. Common when creating conversations or initializing new visitors.

{
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "visitor": {
    "id": "9d1a7c9e-5b21-46f1-9c86-0a2b12345678",
    "type": "anonymous"
  }
}

202 Accepted

The request was accepted but processing is asynchronous. Used when messages are queued for human agent handling.

"Message sent"

Client Error Responses (4xx)

400 Bad Request

The request is malformed or contains invalid parameters. Check your request body, query parameters, and headers.

{
  "error": {
    "message": "Invalid request body. Content is required.",
    "code": "INVALID_REQUEST_BODY",
    "details": {
      "field": "content"
    }
  }
}

Common causes:

• Missing required fields
• Invalid data types
• Malformed JSON
• Invalid parameter values

401 Unauthorized

Authentication credentials are missing, invalid, or expired.

{
  "error": {
    "message": "Authentication required",
    "code": "UNAUTHORIZED"
  }
}

Common causes:

• Missing Authorization header
• Expired session token
• Invalid API key
• Revoked credentials

402 Payment Required

Your current plan doesn't include access to this feature or you've exceeded your plan limits.

{
  "error": {
    "message": "A higher pricing plan is required to access this feature",
    "code": "PAYMENT_REQUIRED",
    "details": {
      "currentPlan": "free",
      "requiredPlan": "pro",
      "feature": "advanced_ai_models"
    }
  }
}

Resolution:

• Upgrade your plan in the dashboard
• Check your current usage and limits

403 Forbidden

You don't have permission to access the requested resource, even with valid authentication.

{
  "error": {
    "message": "Access denied to this conversation",
    "code": "FORBIDDEN"
  }
}

Common causes:

• Attempting to access another visitor's conversation
• Domain restrictions on publishable keys
• Insufficient permissions for the operation

404 Not Found

The requested resource doesn't exist or has been deleted.

{
  "error": {
    "message": "Conversation not found!",
    "code": "CONVERSATION_NOT_FOUND",
    "details": {
      "conversationId": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}

Common causes:

• Invalid resource ID
• Resource was deleted
• Typo in the URL path

409 Conflict

The request conflicts with the current state of the resource.

{
  "error": {
    "message": "Resource already exists",
    "code": "CONFLICT",
    "details": {
      "resource": "conversation",
      "conflictingField": "id"
    }
  }
}

Common causes:

• Duplicate resource creation
• Concurrent modification conflict

422 Unprocessable Entity

The request is syntactically correct but contains semantic errors or fails validation.

{
  "error": {
    "message": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": {
      "field": "content",
      "reason": "Content exceeds maximum length of 10000 characters"
    }
  }
}

Common causes:

• Validation rule violations
• Content too long or too short
• Invalid format or pattern

429 Too Many Requests

You've exceeded the rate limit or usage quota for your plan.

{
  "error": {
    "message": "Rate limit exceeded. Please try again later.",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
      "retryAfter": 60
    }
  }
}

Resolution:

• Wait for the time specified in retryAfter (in seconds)
• Implement exponential backoff
• Check the Retry-After response header
• Upgrade your plan for higher limits

Server Error Responses (5xx)

500 Internal Server Error

An unexpected error occurred on the server. This is not your fault.

{
  "error": {
    "message": "An internal server error occurred",
    "code": "INTERNAL_SERVER_ERROR"
  }
}

What to do:

• Retry the request
• If the error persists, contact support
• Check the status page for incidents

502 Bad Gateway

The server received an invalid response from an upstream service (like an AI model provider).

{
  "error": {
    "message": "Service temporarily unavailable",
    "code": "BAD_GATEWAY",
    "details": {
      "service": "ai_model_service"
    }
  }
}

What to do:

• Retry the request after a short delay
• The issue is usually temporary
• Contact support if it persists

503 Service Unavailable

The server is temporarily unable to handle requests, usually due to maintenance or high load.

{
  "error": {
    "message": "Service temporarily unavailable",
    "code": "SERVICE_UNAVAILABLE",
    "details": {
      "retryAfter": 30
    }
  }
}

What to do:

• Wait and retry after the time specified in retryAfter
• Check the status page
• Implement retry logic with exponential backoff

Error Response Structure

All error responses follow a consistent structure:

{
  "error": {
    "message": "Human-readable error message",
    "code": "MACHINE_READABLE_CODE",
    "details": {
      "additionalContext": "value"
    }
  }
}

Handling Errors

Retry Logic

Implement exponential backoff for temporary errors (429, 500, 502, 503):

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.ok) {
      return response.json();
    }

    // Retry on temporary errors
    if ([429, 500, 502, 503].includes(response.status)) {
      const waitTime = Math.pow(2, i) * 1000; // Exponential backoff
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }

    // Don't retry on client errors
    if (response.status >= 400 && response.status < 500) {
      throw await response.json();
    }
  }

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

Error Handling Best Practices

1. Check Status Codes: Always check the HTTP status code before processing the response
2. Parse Error Details: Use the error.code field for programmatic error handling
3. Log Errors: Log error details for debugging and monitoring
4. User-Friendly Messages: Show appropriate messages to users based on error types
5. Implement Retries: Use exponential backoff for temporary failures
6. Monitor Errors: Track error rates to identify issues early

Need Help?

We're here to help you succeed! Whether you have questions, need assistance with setup, or want to discuss advanced use cases, our team is ready to provide personalized support.

Contact us: support@siteassist.io

We'd love to hear about your use case and help you get the most out of SiteAssist!