Error Codes | Appizer API Documentation

The Appizer API uses standard HTTP status codes to indicate the success or failure of requests.

HTTP Status Codes
Error Response Format
Common Errors
Error Handling Best Practices

HTTP Status Codes

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Authentication failed or missing
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
409	Conflict	Resource conflict (e.g., duplicate ID)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error
503	Service Unavailable	Service temporarily unavailable

Error Response Format

All error responses follow this format:

{
  "error": "Error Type",
  "message": "Detailed error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "Additional context"
  }
}

Common Errors

400 Bad Request

Invalid Request Body:

{
  "error": "Bad Request",
  "message": "Invalid request body",
  "code": "INVALID_REQUEST",
  "details": {
    "field": "event_name",
    "issue": "Field is required"
  }
}

Missing Required Field:

{
  "error": "Bad Request",
  "message": "Missing required field: user_id",
  "code": "MISSING_FIELD"
}

Invalid Field Type:

{
  "error": "Bad Request",
  "message": "Invalid field type",
  "code": "INVALID_TYPE",
  "details": {
    "field": "properties",
    "expected": "object",
    "received": "string"
  }
}

401 Unauthorized

Missing API Key:

{
  "error": "Unauthorized",
  "message": "Missing Authorization header",
  "code": "MISSING_AUTH"
}

Invalid API Key:

{
  "error": "Unauthorized",
  "message": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Expired API Key:

{
  "error": "Unauthorized",
  "message": "API key has been revoked",
  "code": "REVOKED_API_KEY"
}

403 Forbidden

Insufficient Permissions:

{
  "error": "Forbidden",
  "message": "API key does not have permission for this operation",
  "code": "INSUFFICIENT_PERMISSIONS",
  "details": {
    "required_permission": "write",
    "current_permissions": ["read"]
  }
}

404 Not Found

Resource Not Found:

{
  "error": "Not Found",
  "message": "User not found",
  "code": "RESOURCE_NOT_FOUND",
  "details": {
    "resource_type": "user",
    "resource_id": "user_123"
  }
}

409 Conflict

Duplicate Resource:

{
  "error": "Conflict",
  "message": "User ID already exists",
  "code": "DUPLICATE_RESOURCE",
  "details": {
    "field": "user_id",
    "value": "user_123"
  }
}

429 Too Many Requests

Rate Limit Exceeded:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 1000,
    "window": "1 minute",
    "retry_after": 45
  }
}

500 Internal Server Error

Server Error:

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred",
  "code": "INTERNAL_ERROR",
  "details": {
    "request_id": "req_abc123"
  }
}

Error Handling Best Practices

Retry Logic

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

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      
      if (response.ok) {
        return await response.json();
      }
      
      // Retry on 429, 500, 503
      if ([429, 500, 503].includes(response.status)) {
        const waitTime = Math.pow(2, i) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      // Don't retry other errors
      throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Error Logging

Log errors with context for debugging:

try {
  const response = await fetch(url, options);
  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', {
      status: response.status,
      error: error.error,
      message: error.message,
      code: error.code,
      details: error.details,
      url: url,
      timestamp: new Date().toISOString()
    });
  }
} catch (error) {
  console.error('Request failed:', error);
}

User-Friendly Messages

Translate API errors to user-friendly messages:

function getUserFriendlyMessage(error) {
  const messages = {
    'INVALID_REQUEST': 'Please check your input and try again.',
    'MISSING_FIELD': 'Required information is missing.',
    'INVALID_API_KEY': 'Authentication failed. Please check your credentials.',
    'RATE_LIMIT_EXCEEDED': 'Too many requests. Please try again in a moment.',
    'RESOURCE_NOT_FOUND': 'The requested item could not be found.',
    'INTERNAL_ERROR': 'Something went wrong. Please try again later.'
  };
  
  return messages[error.code] || 'An error occurred. Please try again.';
}

Rate Limit Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1640000000

Monitor these headers to avoid hitting rate limits:

const response = await fetch(url, options);
const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');

if (remaining < 10) {
  console.warn(`Low rate limit: ${remaining} requests remaining`);
}

Support

If you encounter persistent errors:

Check the error code and message
Review your request format
Verify your API key and permissions
Check the API Status Page
Contact support@appizer.com with the request_id from error details

Contents