Reference

Complete technical reference for constants, enumerations, error codes, and configuration options.

Overview

This section provides comprehensive reference documentation for:

Response Structure - Standard API response format
HTTP Status Codes - Status codes and meanings
Pagination - Paginated response format
Rate Limiting - Rate limits and headers
Error Codes - Complete error code reference
Language Codes - Supported language codes for STT/TTS

Response Structure

All WIIL API responses follow a standardized structure:

interface ApiResponse<T> {
  success: boolean;        // true if request succeeded, false otherwise
  data: T | null;         // Response data (null on error)
  error: string | null;   // Error message (null on success)
  timestamp: string;      // ISO 8601 timestamp
}

Success Response

{
  "success": true,
  "data": { ... },
  "error": null,
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Response

{
  "success": false,
  "data": null,
  "error": "Detailed error message describing what went wrong",
  "timestamp": "2024-01-15T10:30:00Z"
}

HTTP Status Codes

Success Codes (2xx)

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
204	No Content	Request succeeded with no response body

Client Error Codes (4xx)

Code	Status	Description
400	Bad Request	Invalid request data or malformed JSON
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
409	Conflict	Resource conflict or duplicate
422	Unprocessable Entity	Validation failed
429	Too Many Requests	Rate limit exceeded

Server Error Codes (5xx)

Code	Status	Description
500	Internal Server Error	Server error
502	Bad Gateway	Gateway error
503	Service Unavailable	Service temporarily unavailable
504	Gateway Timeout	Request timeout

Pagination

List endpoints return paginated responses:

interface PaginatedResponse<T> {
  success: true;
  data: {
    items: T[];           // Array of items for current page
    total: number;        // Total number of items
    page: number;         // Current page (1-indexed)
    pageSize: number;     // Items per page
    totalPages: number;   // Total pages
    hasNext: boolean;     // Has next page
    hasPrevious: boolean; // Has previous page
  };
}

Defaults

Parameter	Default	Maximum
pageSize	20	100
page	1	-

Query Parameters

Parameter	Description
`page`	Page number (1-indexed)
`pageSize`	Items per page (max 100)

Rate Limiting

Rate Limit Tiers

Tier	Requests/min	Requests/hour	Requests/day
Standard	100	6,000	100,000
Professional	300	18,000	300,000
Enterprise	Custom	Custom	Custom

Response Headers

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed
`X-RateLimit-Remaining`	Requests remaining
`X-RateLimit-Reset`	Unix timestamp when limit resets
`Retry-After`	Seconds to wait (on 429)

429 Response

{
  "success": false,
  "data": null,
  "error": "Too Many Requests - Rate limit exceeded",
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Codes

Authentication Errors

Code	Status	Description	Solution
`invalid_api_key`	401	API key is invalid or expired	Check API key validity
`missing_api_key`	401	API key not provided	Include `X-WIIL-API-Key` header
`unauthorized`	403	Insufficient permissions	Verify account permissions

Validation Errors

Code	Status	Description	Solution
`validation_error`	400	Request validation failed	Check request schema
`missing_required_field`	400	Required field missing	Include all required fields
`invalid_field_value`	400	Invalid value for field	Check enumeration values
`invalid_format`	400	Field format incorrect	Verify format (email, phone, etc.)

Resource Errors

Code	Status	Description	Solution
`resource_not_found`	404	Resource doesn't exist	Verify resource ID
`conversation_not_found`	404	Conversation not found	Check conversation ID
`deployment_not_found`	404	Deployment config not found	Verify deployment config ID

Rate Limiting Errors

Code	Status	Description	Solution
`rate_limit_exceeded`	429	Too many requests	Implement exponential backoff
`quota_exceeded`	429	Monthly quota exceeded	Upgrade plan or wait for reset

Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000000
Retry-After: 60

Server Errors

Code	Status	Description	Solution
`internal_error`	500	Internal server error	Retry request; contact support if persists
`service_unavailable`	503	Service temporarily unavailable	Retry with exponential backoff

Language Codes

Supported Languages for STT/TTS

Language	Code	Native Speakers
English (US)	`en-US`	300M
English (UK)	`en-GB`	60M
Spanish (Spain)	`es-ES`	40M
Spanish (Mexico)	`es-MX`	130M
French (France)	`fr-FR`	75M
German	`de-DE`	130M
Italian	`it-IT`	85M
Portuguese (Brazil)	`pt-BR`	215M
Portuguese (Portugal)	`pt-PT`	10M
Mandarin Chinese	`zh-CN`	1.1B
Japanese	`ja-JP`	125M
Korean	`ko-KR`	80M
Arabic (Saudi)	`ar-SA`	40M
Hindi	`hi-IN`	600M
Russian	`ru-RU`	260M
Dutch	`nl-NL`	25M
Polish	`pl-PL`	45M
Turkish	`tr-TR`	80M
Swedish	`sv-SE`	10M
Norwegian	`no-NO`	5M

Overview​

Response Structure​

Success Response​

Error Response​

HTTP Status Codes​

Success Codes (2xx)​

Client Error Codes (4xx)​

Server Error Codes (5xx)​

Pagination​

Defaults​

Query Parameters​

Rate Limiting​

Rate Limit Tiers​

Response Headers​

429 Response​

Error Codes​

Authentication Errors​

Validation Errors​

Resource Errors​

Rate Limiting Errors​

Server Errors​

Language Codes​

Supported Languages for STT/TTS​