# API Errors

> Understanding and handling BuildBetter API errors

## Error Format

All API errors follow a consistent format:

```json
{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {
      // Additional error context
    },
    "request_id": "req_123abc"
  }
}
```

## HTTP Status Codes

- Client Errors (4xx)

  Client-side errors requiring request modification
- Server Errors (5xx)

  Server-side errors requiring BuildBetter support

## Common Error Codes

### Authentication Errors

```yaml
auth_errors:
  invalid_credentials:
    status: 401
    message: "Invalid API key or access token"
  
  expired_token:
    status: 401
    message: "Access token has expired"
  
  invalid_scope:
    status: 403
    message: "Token lacks required scope"
  
  unauthorized:
    status: 401
    message: "Authentication required"
```

### Request Errors

```yaml
request_errors:
  invalid_request:
    status: 400
    message: "Malformed request syntax"
  
  invalid_parameters:
    status: 400
    message: "Invalid parameter values"
  
  missing_required:
    status: 400
    message: "Missing required parameters"
  
  not_found:
    status: 404
    message: "Requested resource not found"
```

## Validation Errors

### Field Validation

```json
{
  "error": {
    "code": "validation_error",
    "message": "Invalid field values",
    "details": {
      "fields": {
        "email": "must be a valid email address",
        "name": "cannot be empty",
        "limit": "must be between 1 and 100"
      }
    }
  }
}
```

### Business Logic

```json
{
  "error": {
    "code": "business_rule_violation",
    "message": "Operation not allowed",
    "details": {
      "reason": "Workspace limit reached",
      "current": 5,
      "maximum": 5
    }
  }
}
```

## Rate Limiting

### Rate Limit Errors

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests",
    "details": {
      "rate_limit": {
        "limit": 100,
        "remaining": 0,
        "reset_at": "2024-01-15T10:00:00Z"
      }
    }
  }
}
```

### Rate Limit Headers

```yaml
rate_limit_headers:
  X-RateLimit-Limit: "Maximum requests per window"
  X-RateLimit-Remaining: "Remaining requests in window"
  X-RateLimit-Reset: "Window reset timestamp"
```

## Integration Errors

### Third-Party Service Errors

```yaml
integration_errors:
  connection_failed:
    status: 503
    message: "Unable to connect to service"
  
  invalid_configuration:
    status: 400
    message: "Invalid integration configuration"
  
  sync_failed:
    status: 500
    message: "Data synchronization failed"
```

## Server Errors

### Internal Errors

```yaml
server_errors:
  internal_error:
    status: 500
    message: "Internal server error"
  
  service_unavailable:
    status: 503
    message: "Service temporarily unavailable"
  
  maintenance:
    status: 503
    message: "System under maintenance"
```

> **Warning:** Always include the request\_id when contacting support about API errors.

## Error Handling Best Practices

### Client-Side Handling

```javascript
try {
  const response = await buildbetter.api.call();
} catch (error) {
  if (error.status === 401) {
    // Handle authentication errors
  } else if (error.status === 429) {
    // Handle rate limiting
  } else if (error.status >= 500) {
    // Handle server errors
  }
}
```

### Retry Strategies

```yaml
retry_recommendations:
  5xx_errors:
    - Use exponential backoff
    - Maximum 3 retries
    - Add jitter to prevent thundering herd
  
  rate_limits:
    - Honor X-RateLimit-Reset header
    - Implement request queuing
    - Consider batch operations
```

## Debugging Errors

### 1. Check Error Details

Review the error code and message

### 2. Verify Request

Confirm request format and parameters

### 3. Check Documentation

Review endpoint requirements

### 4. Contact Support

Provide request\_id and details

## Error Categories

### Resource Errors

```yaml
resource_errors:
  not_found:
    status: 404
    message: "Resource does not exist"
  
  already_exists:
    status: 409
    message: "Resource already exists"
  
  gone:
    status: 410
    message: "Resource no longer available"
```

### Permission Errors

```yaml
permission_errors:
  forbidden:
    status: 403
    message: "Permission denied"
  
  workspace_access:
    status: 403
    message: "No access to workspace"
  
  plan_limit:
    status: 403
    message: "Plan limit exceeded"
```

> **Note:** Some errors may include additional context in the details field to help with debugging.

## Support Resources

### Getting Help

- Include request\_id in support tickets
- Provide request and response details
- Describe expected behavior
- Include error timestamps

### Error Monitoring

```yaml
monitoring_recommendations:
  logging:
    - Log all API errors
    - Include request context
    - Track error patterns
    - Monitor retry attempts
  
  alerting:
    - Set up error thresholds
    - Monitor rate limits
    - Track error rates
    - Alert on critical errors
```

> **Tip:** Use the request\_id to correlate errors across your systems and BuildBetter's logs.

> **Info:** Our support team is available to help investigate and resolve API errors.