BuildBetter Docs

API Errors

Error Format

All API errors follow a consistent format:

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

HTTP Status Codes

Common Error Codes

Authentication Errors

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

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

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

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

Rate Limiting

Rate Limit Errors

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

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

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

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

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

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

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

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

Error Monitoring

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.