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

Status Code	Name	Description
200	OK	The request was successful. The response body contains the requested data.
201	Created	A new resource was successfully created (e.g., new conversation or visitor).
202	Accepted	The request was accepted and queued for processing (e.g., message queued for human agent).
400	Bad Request	The request was invalid or malformed. Check the request body and parameters.
401	Unauthorized	Authentication is required or the provided credentials are invalid.
402	Payment Required	A higher pricing plan is required to access this feature or resource.
403	Forbidden	The authenticated user doesn’t have permission to access the requested resource.
404	Not Found	The requested resource doesn’t exist or couldn’t be found.
409	Conflict	The request conflicts with the current state of the resource.
422	Unprocessable Entity	The request was well-formed but contains semantic errors or validation failures.
429	Too Many Requests	Rate limit exceeded or usage quota reached. Retry after the specified time.
500	Internal Server Error	An unexpected error occurred on the server. Contact support if this persists.
502	Bad Gateway	The server received an invalid response from an upstream service (e.g., AI provider).
503	Service Unavailable	The server is temporarily unable to handle the request. Try again later.

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"
    }
  }
}

Field	Description
`error.message`	Human-readable description of what went wrong
`error.code`	Machine-readable error code for programmatic handling
`error.details`	Optional object with additional context about the error

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

Check Status Codes: Always check the HTTP status code before processing the response
Parse Error Details: Use the error.code field for programmatic error handling
Log Errors: Log error details for debugging and monitoring
User-Friendly Messages: Show appropriate messages to users based on error types
Implement Retries: Use exponential backoff for temporary failures
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!