API Reference

Error Handling

Understanding and handling AMP API errors.

Error Response Format

All AMP errors follow a consistent format:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 60 seconds.",
    "details": {
      "limit": 100,
      "window": "60s",
      "retryAfter": 42
    },
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Codes

Authentication Errors

Code	Description	Resolution
UNAUTHORIZED	Invalid or missing API key	Check your API key
FORBIDDEN	API key lacks permissions	Check key permissions
KEY_EXPIRED	API key has expired	Generate new key

Rate Limiting

Code	Description	Resolution
RATE_LIMIT_EXCEEDED	Too many requests	Implement exponential backoff
QUOTA_EXCEEDED	Monthly quota reached	Upgrade plan or wait for reset

Validation Errors

Code	Description
INVALID_USER_ID	User ID missing or invalid
INVALID_TASK	Task description invalid
INVALID_REQUEST_ID	Request ID not found

Error Handling Strategies

Basic Try-Catch

try {
  const context = await amp.getContext({
    userId: user.id,
    task: query
  });
} catch (error) {
  if (error.code === 'RATE_LIMIT_EXCEEDED') {
    // Wait and retry
    await sleep(error.details.retryAfter * 1000);
    return retry();
  }

  if (error.code === 'UNAUTHORIZED') {
    // API key issue
    console.error('Invalid API key');
    throw error;
  }

  // Unknown error - use fallback
  return getDefaultContext();
}

Exponential Backoff

async function getContextWithRetry(params, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await amp.getContext(params);
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED' && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000;
        await sleep(delay);
        continue;
      }
      throw error;
    }
  }
}

Graceful Degradation

let context;

try {
  context = await amp.getContext({ userId, task });
} catch (error) {
  // Log error but don't fail
  console.warn('AMP unavailable, using defaults:', error);

  // Fall back to sensible defaults
  context = {
    suggestedFraming: 'achievement',
    communicationStyle: 'conversational',
    complexity: 'break_into_steps',
    confidence: 0.5
  };
}

// Continue with context (AMP or fallback)

💡 Best Practice: Always have a fallback strategy. Your agent should work even if AMP is temporarily unavailable.

HTTP Status Codes

200 - Success
400 - Bad Request (validation error)
401 - Unauthorized (invalid API key)
403 - Forbidden (insufficient permissions)
429 - Too Many Requests (rate limited)
500 - Internal Server Error
503 - Service Unavailable

Monitoring & Logging

// Log all errors for monitoring
amp.on('error', (error) => {
  logger.error('AMP Error', {
    code: error.code,
    message: error.message,
    requestId: error.requestId,
    userId: error.context?.userId
  });

  // Send to monitoring service
  sentry.captureException(error);
});