Error Codes

Complete reference for Appizer API error codes

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

Contents

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:

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

Common Errors

400 Bad Request

Invalid Request Body:

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

Missing Required Field:

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

Invalid Field Type:

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

401 Unauthorized

Missing API Key:

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

Invalid API Key:

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

Expired API Key:

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

403 Forbidden

Insufficient Permissions:

json
{
  "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:

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

409 Conflict

Duplicate Resource:

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

429 Too Many Requests

Rate Limit Exceeded:

json
{
  "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:

json
{
  "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):

javascript
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:

javascript
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:

javascript
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:

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

Monitor these headers to avoid hitting rate limits:

javascript
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:

  1. Check the error code and message
  2. Review your request format
  3. Verify your API key and permissions
  4. Check the API Status Page
  5. Contact support@appizer.com with the request_id from error details
On this page